Troubleshooting

Common problems and solutions.

Development Issues

EACCES: permission denied

npm cache clean --force
# If that doesn't work:
sudo chown -R $(whoami) ~/.npm

Clear the Build Cache

Stop your dev server, delete the .trigger folder in your project root, then restart:

rm -rf .trigger
npx trigger.dev@latest dev

Yarn PnP Conflicts

Error: Could not resolve "@trigger.dev/core" with Yarn Plug'n'Play

Check for a .pnp.cjs file in your home directory and remove it.

Node.js Version Requirements

Error: The requested module 'node:events' does not provide an export named 'addAbortListener'

Node Version	Minimum
18	18.20+
20	20.5+
21	21.0+
22	22.0+

Deployment Issues

Failed to build project image: Error building image

• Check the full build log linked in the error
• Try --force-local-build as fallback
• Ask for help in Discord (share logs privately)

Error: failed to solve: failed to resolve source metadata for docker.io/docker/dockerfile:1

After uninstalling Docker Desktop, remove or update ~/.docker/config.json.

No loader is configured for ".node" files

Native binaries can't be bundled. Add to build.external:

export default defineConfig({
  build: { external: ["your-native-package"] }
});

Cannot find module '/app/lib/worker.js' (pino)

Add pino to build.external:

build: { external: ["pino", "pino-pretty"] }

reactDOMServer.renderToPipeableStream is not a function (react-email)

build: {
  external: ["react", "react-dom", "@react-email/render", "@react-email/components"]
}

Cannot find matching keyid

Node.js v22 + corepack issue. Fix:

• Downgrade to Node.js v20 (LTS), or
• npm i -g corepack@latest

resource_exhausted

Build hit resource limits on remote build infrastructure. Try local build:

npx trigger.dev deploy --force-local-build

Runtime Issues

Environment variable not found

Your deployed tasks run separately from your app. Set environment variables in the Trigger.dev dashboard → Environment Variables.

Error: @prisma/client did not initialize yet

You need the prismaExtension in your trigger.config.ts. See Prisma extension.

Database Requires IPv4

Trigger.dev only supports IPv4 connections. Use an IPv4-compatible connection string.

Parallel waits are not supported

You cannot use Promise.all() with wait functions. Use batchTriggerAndWait() instead:

// Wrong:
await Promise.all([task1.triggerAndWait(p), task2.triggerAndWait(p)]);

// Right:
const results = await task1.batchTriggerAndWait([{ payload: p1 }, { payload: p2 }]);
// Or for different tasks:
const results = await batch.triggerAndWait([
  { id: "task-1", payload: p1 },
  { id: "task-2", payload: p2 },
]);

Parent task finishes too soon

Always await trigger calls:

// Wrong:
childTask.trigger(payload); // fire and forget — parent may exit before child starts

// Right:
await childTask.trigger(payload); // wait for trigger to be acknowledged
await childTask.triggerAndWait(payload); // wait for child to complete

COULD_NOT_FIND_EXECUTOR

Don't dynamically import child tasks. Use top-level imports:

// Wrong:
const { myChildTask } = await import("./my-child-task");

// Right:
import { myChildTask } from "./my-child-task";

Or use tasks.trigger() without importing:

await batch.triggerAndWait([{ id: "my-child-task", payload: data }]);

Rate Limit Exceeded

Don't call trigger() in a loop. Use batchTrigger() instead:

// Wrong (1 API call per item):
for (const item of items) {
  await myTask.trigger(item);
}

// Right (1 API call for all):
await myTask.batchTrigger(items.map((item) => ({ payload: item })));

TASK_RUN_STALLED_EXECUTING

Task blocked the event loop. Use heartbeats.yield() for CPU-intensive loops:

import { heartbeats } from "@trigger.dev/sdk";

for (const row of bigDataset) {
  await heartbeats.yield(); // yields when needed
  process(row);
}

Runs Stuck in Queue

Check concurrency limits in the dashboard. Solutions:

• Increase environment concurrency limit (paid plans)
• Review task concurrencyLimit settings
• Check for stuck/stalled runs blocking the queue

Framework Issues

NestJS Swallows Errors

Avoid using NestFactory.createApplicationContext() inside tasks — NestJS global exception filters swallow errors. Use native TypeScript services instead.

React is not defined

Add to your task file:

import React from "react";

Or set in tsconfig.json:

{ "compilerOptions": { "jsx": "react-jsx" } }

Next.js Build Fails in CI (missing API key)

// Add to affected pages:
export const dynamic = "force-dynamic";

Passing Event Handlers to React Components

// Works:
<Button onClick={() => myTask.trigger(data)}>Trigger</Button>

// Doesn't work:
<Button onClick={myTask.trigger}>Trigger</Button>