Troubleshooting

Fresh

Common Trigger.dev errors and how to fix them.

Development Issues

Task Not Appearing in Dashboard

Symptom: Task file created but not showing up in dashboard.

Causes & Fixes:

1. File is outside the /trigger directory

   • Check trigger.config.ts → dirs setting
   • Move file inside the configured trigger directory

2. Dev server not restarted after adding file

   • Stop and restart npx trigger.dev@latest dev

3. Export missing

   • Make sure the task is exported: export const myTask = task({...})

4. Syntax error in the file

   • Check terminal output for TypeScript/parse errors

---

Retries Not Triggering

Symptom: Task fails but doesn't retry.

Fix: Your run function must throw an error to trigger retry. If you catch errors, Trigger.dev considers the run successful.

// WRONG — swallowed error, no retry
run: async (payload) => {
  try {
    await riskyOperation();
  } catch (e) {
    console.error(e); // Error eaten, no retry
  }
}

// CORRECT — rethrow to trigger retry
run: async (payload) => {
  try {
    await riskyOperation();
  } catch (e) {
    console.error(e);
    throw e; // Rethrow — triggers retry
  }
}

---

Version Mismatch Error

Symptom: Version mismatch detected or SDK version errors.

Fix: When running dev, accept the package update prompt:

? @trigger.dev/* packages are outdated. Update now? › Yes

Or manually update:

npm update @trigger.dev/sdk @trigger.dev/build

---

CLI Login Fails

Symptom: Login hangs or browser doesn't open.

Fix:

npx trigger.dev@latest logout
npx trigger.dev@latest login

If using multiple profiles:

npx trigger.dev@latest login --profile production

---

Deployment Issues

"Failed to build project image: Error building image"

Cause: Remote build provider issue or code error.

Fixes:

1. Check the build log link in the error message

2. Try local build:

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

   Requires Docker + Docker Buildx installed.

3. Dry run to see what's being built:

   npx trigger.dev@latest deploy --dry-run

4. Enable verbose debug:

   npx trigger.dev@latest deploy --log-level debug

---

"No loader is configured for .node files"

Cause: Native Node.js addon package can't be bundled.

Fix: Add to build.external in trigger.config.ts:

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

export default defineConfig({
  project: "proj_xxx",
  build: {
    external: ["your-native-package"],  // e.g., "sharp", "canvas"
  },
});

---

"Cannot find matching keyid" (Node v22 + corepack)

Cause: Incompatibility between Node.js v22 and corepack.

Fix Option A (recommended):

npm i -g corepack@latest

Fix Option B: Downgrade to Node.js 20 LTS.

---

"Deployment encountered an error"

Cause: Various — check the guidance below the error.

Fixes:

1. Look for the link to build logs in the error output
2. Join Trigger.dev Discord → Help forum
3. Share your build URL privately (not publicly — logs may contain secrets)

---

Runtime Issues

Task Stuck / Never Completing

Symptom: Run shows "Executing" indefinitely.

Causes & Fixes:

1. Infinite loop in code — add logging to track progress
2. External API hanging — add timeouts to fetch calls:

   const controller = new AbortController();
   setTimeout(() => controller.abort(), 30000); // 30s timeout
   await fetch(url, { signal: controller.signal });

3. maxDuration exceeded — increase or remove it
4. Awaiting a cancelled child task — use onCancel hook for cleanup

---

Batch Trigger Rate Limited

Symptom: BatchTriggerError with isRateLimited: true.

Fix:

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

try {
  await myTask.batchTrigger(items);
} catch (error) {
  if (error instanceof BatchTriggerError && error.isRateLimited) {
    const waitMs = error.retryAfterMs ?? 10000;
    await new Promise(r => setTimeout(r, waitMs));
    // Retry...
  }
}

---

Large Payload Errors

Symptom: Payload too large or payload rejected.

Limits:

• Hard limit: 10MB
• Auto-S3 upload: above 512KB
• Task output: 100MB limit

Fix for very large payloads:

// Upload to S3 first, pass URL
const presignedUrl = await uploadToS3(largeData);
await myTask.trigger({ url: presignedUrl });

---

Child Task triggerAndWait Stuck

Symptom: Parent hangs waiting for child that never completes.

Common causes:

1. Child task threw an error with no retries left — check child run in dashboard

2. Version mismatch — triggerAndWait locks child to parent version, ensure that version is still active

3. Using Promise.all() with triggerAndWait — don't do this:

   // WRONG
   const [r1, r2] = await Promise.all([
     task1.triggerAndWait(a),
     task2.triggerAndWait(b)
   ]);
   
   // CORRECT
   const results = await batch.triggerAndWait([
     { id: "task-1", payload: a },
     { id: "task-2", payload: b },
   ]);

---

onFailure Not Firing

Symptom: Task fails but onFailure hook doesn't execute.

Note: onFailure only fires after all retries are exhausted. It also doesn't fire for:

• Crashed status
• System failures
• Canceled runs

Use onComplete for guaranteed post-run execution.

---

Getting More Help

1. Check run logs in the Trigger.dev dashboard
2. Trigger.dev Discord: trigger.dev/discord
3. GitHub Issues: github.com/triggerdotdev/trigger.dev
4. Debug mode: npx trigger.dev@latest dev --log-level debug