@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/troubleshooting-zod.mdx

@@ -0,0 +1,158 @@
+---
+title: "Zod"
+description: "Resolve Zod typechecking, test, and deployment errors when upgrading to Trigger.dev v4.6."
+---
+
+**Trigger.dev v4.6 uses Zod 4 by default. Zod 3.25.56 and later 3.x releases remain supported.**
+
+Use this guide if typechecking, tests, or deployment fail after upgrading. The supported project dependency range is `^3.25.56 || ^4.0.0`.
+
+| Your project's Zod dependency | What to do |
+| --- | --- |
+| No direct Zod dependency | No Zod-specific change is needed. Trigger.dev installs a compatible runtime dependency automatically. |
+| Zod below 3.25.56 | Upgrade before using Trigger.dev v4.6. These versions are unsupported. |
+| Zod 3.25.56 or later in the 3.x release line | Keep using your Zod 3 schemas with supported SDK APIs. Review the cross-major caveats below. |
+| Zod 4.x | Supported and the recommended default. |
+
+Passing your own supported Zod 3 schema to [`schemaTask`](/tasks/schemaTask) or `toolTask` remains supported. This does not make Zod 3 and Zod 4 schemas interchangeable when you compose or inspect them yourself.
+
+## Typechecking, tests, or deployment fail after upgrading
+
+An older Zod installation can be missing the entry points, types, or schema behavior that Trigger.dev v4.6 requires.
+
+Expect TypeScript errors when an unsupported version is resolved, particularly with `skipLibCheck: false`. Tests may also fail when they import or execute schemas. Deployment loads your task code, so an incompatible runtime installation causes deployment errors even if your local tooling skips typechecking. A passing local test suite does not establish that an unsupported version is safe to deploy.
+
+Symptoms include missing `zod/v4` or `zod/v4/core` exports, missing Zod types, incompatible generic parameters, and errors while loading tasks. The exact failure depends on the version and dependency tree; not every unsupported version fails at the same stage.
+
+### Check the installed version
+
+Inspect the resolved dependencies in the package that contains your tasks, not only the version range in `package.json`:
+
+<CodeGroup>
+```bash npm
+npm ls zod
+```
+
+```bash pnpm
+pnpm why zod
+```
+
+```bash bun
+bun pm ls --all
+```
+</CodeGroup>
+
+Check the lockfile and any dependency overrides or resolutions as well. An override can keep an old Zod version installed even after you update a direct dependency.
+
+### Update Zod
+
+Choose whether to move your application to Zod 4 or keep its existing Zod 3 schemas:
+
+<Tabs>
+  <Tab title="Move to Zod 4">
+    Install the latest Zod 4 release:
+
+    <CodeGroup>
+    ```bash npm
+    npm install zod@4
+    ```
+
+    ```bash pnpm
+    pnpm add zod@4
+    ```
+
+    ```bash bun
+    bun add zod@4
+    ```
+    </CodeGroup>
+
+    Review [Zod's migration guide](https://zod.dev/v4/changelog) for changes to your own schemas and error handling.
+  </Tab>
+  <Tab title="Stay on Zod 3">
+    Install the latest Zod 3 patch rather than pinning the minimum supported version:
+
+    <CodeGroup>
+    ```bash npm
+    npm install zod@3
+    ```
+
+    ```bash pnpm
+    pnpm add zod@3
+    ```
+
+    ```bash bun
+    bun add zod@3
+    ```
+    </CodeGroup>
+
+    Your existing `import { z } from "zod"` continues to use Zod 3. Trigger.dev's own schemas use the Zod 4 implementation included in the supported Zod 3 package.
+  </Tab>
+</Tabs>
+
+Other dependencies can require a higher minimum than Trigger.dev. For example, an AI SDK dependency may require Zod 3.25.76 or Zod 4. Meet those peer requirements too; do not force a lower version across every dependency.
+
+### Verify the update
+
+- Commit the updated manifest and lockfile, and make sure CI uses them.
+- Recheck the installed Zod versions in your local and deployment environments.
+- Run your project's TypeScript checks and tests, including code that constructs or inspects schemas.
+- Keep the CLI and SDK versions aligned using the [package upgrade guide](/upgrading-packages), then retry deployment.
+
+Do not use `skipLibCheck` or ignored peer-dependency warnings as a compatibility fix. They do not change the runtime package that deployment loads. You do not need to add Zod as a direct dependency if your application does not import it.
+
+## Parsing still fails with a supported Zod 3 version
+
+Supporting a Zod 3 schema as an SDK input is different from nesting a Trigger.dev-exported Zod 4 schema inside a Zod 3 object. Cross-major composition can fail during typechecking or parsing.
+
+For example, this mixes a Zod 3 object with a Zod 4 `RetryOptions` schema:
+
+```ts incompatible-schemas.ts
+import { z } from "zod"; // Project dependency is Zod 3.
+import { RetryOptions } from "@trigger.dev/core/v3";
+
+const schema = z.object({ retry: RetryOptions });
+schema.parse({ retry: {} });
+```
+
+Use Zod 4 for every schema in the composed object. The `zod/v4` entry point is available in both supported Zod 3 packages and Zod 4 packages:
+
+```ts compatible-schemas.ts
+import { z } from "zod/v4";
+import { RetryOptions } from "@trigger.dev/core/v3";
+
+const schema = z.object({ retry: RetryOptions });
+schema.parse({ retry: {} });
+```
+
+Alternatively, keep the Zod 3 and Trigger.dev schemas separate and call each schema's parser independently. You do not need to migrate unrelated application schemas to use this approach.
+
+## An `instanceof` check stops matching
+
+A Zod 4 error is not an instance of the Zod 3 `ZodError` constructor. A constructor check against your project's Zod 3 import can stop matching errors produced by Trigger.dev's schemas:
+
+```ts mismatched-error-check.ts
+import { z } from "zod"; // Project dependency is Zod 3.
+import { RetryOptions } from "@trigger.dev/core/v3";
+
+const result = RetryOptions.safeParse({ maxAttempts: "invalid" });
+
+if (!result.success) {
+  console.log(result.error instanceof z.ZodError); // false
+}
+```
+
+Use the result returned by the schema you called instead of a constructor from another Zod installation:
+
+```ts schema-error-handling.ts
+import { RetryOptions } from "@trigger.dev/core/v3";
+
+const result = RetryOptions.safeParse({ maxAttempts: "invalid" });
+
+if (!result.success) {
+  console.error(result.error.issues);
+}
+```
+
+The same caveat applies to checks such as `schema instanceof z.ZodObject`. Multiple installed copies can also have different constructors, even within the same major version. Prefer parsing and the returned validation result over inspecting classes or private fields such as `_def`.
+
+These examples are not an exhaustive list of cross-major differences. If errors remain after updating, check which Zod implementation creates each schema and which code composes, parses, or inspects it.

package/docs/troubleshooting.mdx

@@ -0,0 +1,414 @@
+---
+title: "Common problems"
+description: "Some common problems you might experience and their solutions"
+---
+
+import NextjsTroubleshootingMissingApiKey from "/snippets/nextjs-missing-api-key.mdx";
+import NextjsTroubleshootingButtonSyntax from "/snippets/nextjs-button-syntax.mdx";
+import RateLimitHitUseBatchTrigger from "/snippets/rate-limit-hit-use-batchtrigger.mdx";
+import CorepackError from "/snippets/corepack-error.mdx";
+
+## Development
+
+### `EACCES: permission denied`
+
+If you see this error:
+
+```
+6090 verbose stack Error: EACCES: permission denied, rename '/Users/user/.npm/_cacache/tmp/f1bfea11' -> '/Users/user/.npm/_cacache/content-v2/sha512/31/d8/e094a47a0105d06fd246892ed1736c02eae323726ec6a3f34734eeb71308895dfba4f4f82a88ffe7e480c90b388c91fc3d9f851ba7b96db4dc33fbc65528'
+```
+
+First, clear the npm cache:
+
+```sh
+npm cache clean --force
+```
+
+Then change the permissions of the npm folder (if 1 doesn't work):
+
+```sh
+sudo chown -R $(whoami) ~/.npm
+```
+
+### Clear the build cache
+
+Ensure you have stopped your local dev server then locate the hidden `.trigger` folder in your project and delete it. You can then restart your local dev server.
+
+### Yarn Plug'n'Play conflicts
+
+If you see errors like this when running `trigger.dev dev`:
+
+```
+Could not resolve "@trigger.dev/core"
+The Yarn Plug'n'Play manifest forbids importing "@trigger.dev/core" here because it's not listed as a dependency of this package
+```
+
+And you're using Yarn v1.22 or another package manager, check if you have a `.pnp.cjs` file in your home directory. This can happen if you previously had Yarn Plug'n'Play enabled globally. Remove the `.pnp.cjs` file to resolve the issue.
+
+### `Connection error` when logging in
+
+If you see "Connection error" when running `trigger login` (or "Failed to create authorization code"), try these in order:
+
+1. **Clear saved auth and retry:** `npx trigger.dev@latest logout`, then `npx trigger.dev@latest login` again. Sometimes an invalid config is cached.
+2. **VPN or firewall:** Disconnect from VPN or check firewall/proxy; try `npx trigger.dev@latest login --log-level debug` for more detail.
+3. **TLS / certificate store:** Node may use a different CA store than your OS (e.g. `curl` works but the CLI fails). Try `export NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem` (macOS/Linux) then login again, or reinstall Node so it gets updated certs. Behind a corporate proxy or custom CA? Set `NODE_EXTRA_CA_CERTS` to that CA file.
+
+### Runs never dequeue in dev
+
+If runs sit in the queue and never start while running `trigger.dev dev`, check whether you have more than one local instance running against the same project. Each project has a single dev environment, and only one `trigger.dev dev` instance can consume from it at a time, so a second instance causes runs to be split between them and some appear stuck. Keep a single `trigger.dev dev` running per project. [Upvote isolated dev sessions](https://triggerdev.featurebase.app/p/isolated-dev-sessions-for-multiple-local-trigger-dev-instances) if you need to run multiple local instances.
+
+## Deployment
+
+Running the [trigger.dev deploy] command builds and deploys your code. Sometimes there can be issues building your code.
+
+You can run the deploy command with `--log-level debug` at the end. This will spit out a lot of information about the deploy. If you can't figure out the problem from the information below please join [our Discord](https://trigger.dev/discord) and create a help forum post. Do NOT share the extended debug logs publicly as they might reveal private information about your project.
+
+You can also review the build by supplying the `--dry-run` flag. This will build your project but not deploy it. You can then inspect the build output on your machine.
+
+Here are some common problems and their solutions:
+
+### `Failed to build project image: Error building image`
+
+There should be a link below the error message to the full build logs on your machine. Take a look at these to see what went wrong. Join [our Discord](https://trigger.dev/discord) and you share it privately with us if you can't figure out what's going wrong. Do NOT share these publicly as the verbose logs might reveal private information about your project.
+
+### `Error: failed to solve: failed to resolve source metadata for docker.io/docker/dockerfile:1`
+
+If you see this error after uninstalling Docker Desktop:
+
+```
+Error: failed to solve: failed to resolve source metadata for docker.io/docker/dockerfile:1: error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH
+```
+
+This happens because Docker Desktop left behind a config file that's still trying to use its credential store. To fix this, remove or update the `~/.docker/config.json` file. You don't need Docker Desktop installed to use Trigger.dev.
+
+### `Deployment encountered an error`
+
+Usually there will be some useful guidance below this message. If you can't figure out what's going wrong then join [our Discord](https://trigger.dev/discord) and create a Help forum post with a link to your deployment.
+
+### `resource_exhausted`
+
+If you see a `resource_exhausted` error during deploy, the build may have hit resource limits on our build infrastructure. Try our [native builder](https://trigger.dev/changelog/deployments-with-native-builds) by deploying with the `--native-build` flag.
+
+### `No loader is configured for ".node" files`
+
+This happens because `.node` files are native code and can't be bundled like other packages. To fix this, add your package to [`build.external`](/config/config-file#external) in the `trigger.config.ts` file like this:
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    external: ["your-node-package"],
+  },
+});
+```
+
+### `Cannot find module '/app/lib/worker.js"` when using pino
+
+If you see this error, add pino (and any other associated packages) to your `external` build settings in your `trigger.config.ts` file. Learn more about the `external` setting in the [config docs](/config/config-file#external).
+
+### `Failed to index deployment` with `Column must be greater than or equal to 0, got -1`
+
+This can occur when using `runtime: "bun"` during the indexing phase (we load and execute your task files to discover exports). A short-term workaround is to [pnpm patch](https://pnpm.io/cli/patch) the `source-map` package. See [this GitHub issue](https://github.com/triggerdotdev/trigger.dev/issues/3045) for the patch details.
+
+### `reactDOMServer.renderToPipeableStream is not a function` when using react-email
+
+If you see this error when using `@react-email/render`:
+
+```
+TypeError: reactDOMServer.renderToPipeableStream is not a function
+    at __spreadValues.selectors (file:///node_modules/.pnpm/@react-email+render@1.0.6_react-dom@19.0.0_react@19.0.0/node_modules/@react-email/render/dist/node/index.mjs:162:37)
+```
+
+This happens because react-email packages have bundling conflicts with our build process. To fix this, add the react-email packages to your `external` build settings in your `trigger.config.ts` file:
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    external: ["react", "react-dom", "@react-email/render", "@react-email/components"],
+  },
+});
+```
+
+<CorepackError />
+
+## Project setup issues
+
+### `The requested module 'node:events' does not provide an export named 'addAbortListener'`
+
+If you see this error it means you're not a supported version of Node:
+
+```
+SyntaxError: The requested module 'node:events' does not provide an export named 'addAbortListener'
+at ModuleJob._instantiate (node:internal/modules/esm/module_job:123:21)
+at async ModuleJob.run (node:internal/modules/esm/module_job:189:5)
+
+Node.js v19.9.0
+```
+
+You need to be on at least these minor versions:
+
+| Version | Minimum |
+| ------- | ------- |
+| 18      | 18.20+  |
+| 20      | 20.5+   |
+| 21      | 21.0+   |
+| 22      | 22.0+   |
+
+## Runtime issues
+
+### Runs stuck in "Pending version"
+
+A run sits in **Pending version** when the version deployed to that environment doesn't contain the run's task, or doesn't contain the queue it was triggered on. The run isn't lost: unless it's pinned to a specific deployment (see the last cause below), it starts automatically once a version containing both is deployed.
+
+Usually one of:
+
+- **The task isn't in the deployed version.** It was renamed or removed, or the deploy adding it hasn't landed yet. Check the Tasks page for that environment.
+- **The queue doesn't exist in the deployed version.** Overriding `queue` at trigger time only works if a deployed task declares that queue — see [Queues](/queues).
+- **You triggered into the wrong organization, project or environment.** Check the secret key you triggered with belongs to the same place you deployed to.
+- **A later deploy removed or renamed the task or queue while the run was waiting.** Most likely with `delay`. Pin the run to a version to avoid this: `trigger(payload, { delay: "1h", version: "20260227.2" })`. See [version locking](/deployment/overview#version-locking).
+- **The run is pinned to an external deployment id that hasn't arrived.** This is [version skew protection](/deployment/atomic-deployment#waiting-and-expiry), and it behaves differently: only a deployment carrying the matching id releases the run, and it expires after 1 hour if none does.
+
+### `Environment variable not found:`
+
+Your code is deployed separately from the rest of your app(s) so you need to make sure that you set any environment variables you use in your tasks in the Trigger.dev dashboard. [Read the guide](/deploy-environment-variables).
+
+### `Error: @prisma/client did not initialize yet.`
+
+Prisma uses code generation to create the client from your schema file. This means you need to add a bit of config so we can generate this file before your tasks run: [Read the guide](/config/extensions/prismaExtension).
+
+### Database connection requires IPv4
+
+Trigger.dev currently only supports IPv4 database connections. If your database provider only provides an IPv6 connection string, you'll need to use an IPv4 address instead. [Upvote IPv6 support](https://triggerdev.featurebase.app/p/support-ipv6-database-connections).
+
+### `Parallel waits are not supported`
+
+In the current version, you can't perform more that one "wait" in parallel.
+
+Waits include:
+
+- `wait.for()`
+- `wait.until()`
+- `task.triggerAndWait()`
+- `task.batchTriggerAndWait()`
+- `retry.onThrow()`
+- And any of our functions with `wait` in the name.
+
+This restriction exists because we suspend the task server after a wait, and resume it when the wait is done. At the moment, if you do more than one wait, the run will never continue when deployed, so we throw this error instead.
+
+The most common situation this happens is if you're using `Promise.all` around some of our wait functions. Instead of doing this use our built-in functions for [triggering tasks](/triggering#triggering-from-inside-another-task). We have functions that allow you to trigger different tasks in parallel.
+
+### When triggering subtasks the parent task finishes too soon
+
+Make sure that you always use `await` when you call `trigger`, `triggerAndWait`, `batchTrigger`, and `batchTriggerAndWait`. If you don't then it's likely the task(s) won't be triggered because the calling function process can be terminated before the networks calls are sent.
+
+### `COULD_NOT_FIND_EXECUTOR`
+
+If you see a `COULD_NOT_FIND_EXECUTOR` error when triggering a task, it may be caused by dynamically importing the child task. When tasks are dynamically imported, the executor may not be properly registered.
+
+Use a top-level import instead:
+
+```ts
+import { myChildTask } from "~/trigger/my-child-task";
+
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: string) => {
+    await myChildTask.trigger({ payload: "data" });
+  },
+});
+```
+
+Alternatively, use `tasks.trigger()` or `batch.triggerAndWait()` without importing the task:
+
+```ts
+import { batch } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: string) => {
+    await batch.triggerAndWait([{ id: "my-child-task", payload: "data" }]);
+  },
+});
+```
+
+### Rate limit exceeded
+
+<RateLimitHitUseBatchTrigger />
+
+View the [rate limits](/limits) page for more information.
+
+### Runs waiting in queue due to concurrency limits
+
+If runs are staying in the `QUEUED` state for extended periods, check your concurrency usage in the dashboard. Review how many runs are `EXECUTING` or `DEQUEUED` (these count against limits) and check if any runs are stuck in `EXECUTING` state, as they may be blocking new runs.
+
+**Solutions:**
+
+- **Increase concurrency limits** - If you're on a paid plan, increase your environment concurrency limit via the dashboard
+- **Review concurrency settings** - Check if your tasks have restrictive `concurrency` settings, or your queues a restrictive legacy `concurrencyLimit`. See [Concurrency](/concurrency)
+- **Check for stuck runs** - See if stalled runs are blocking new executions
+
+### Runs queued because a billing limit was reached
+
+If your organization reaches a billing limit, billable environments (`production`, `staging`, and `preview`) pause: new runs still queue, but they won't start executing until you raise or remove the limit and choose whether to resume or cancel the queued runs. See [Billing limits and alerts](/billing-limits) for the full flow.
+
+### `Crypto is not defined`
+
+This can happen in different situations, for example when using plain strings as idempotency keys. Support for `Crypto` without a special flag was added in Node `v19.0.0`. You will have to upgrade Node - we recommend even-numbered major releases, e.g. `v20` or `v22`. Alternatively, you can switch from plain strings to the `idempotencyKeys.create` SDK function. [Read the guide](/idempotency).
+
+### Task run stalled executing
+
+If you see a `TASK_RUN_STALLED_EXECUTING` error it means that we didn't receive a heartbeat from your task before the stall timeout. We automatically heartbeat runs every 30 seconds, and the heartbeat timeout is 5 minutes.
+
+<Note>
+
+If this was a dev run, then most likely the `trigger.dev dev` CLI was stopped, and it wasn't an issue with your code.
+
+</Note>
+
+These errors can happen when code inside your task is blocking the event loop for too long. The most likely cause would be an accidental infinite loop. It could also be a CPU-heavy operation that's blocking the event loop, like nested loops with very large arrays.
+
+If you use **Prisma 7.x**, query compilation and caching run on the main thread and can block the event loop during heavy or repeated database work. In tasks that do a lot of Prisma calls (e.g. in loops or many sequential queries), add `await heartbeats.yield()` periodically so the event loop can run and send heartbeats.
+
+We recommend reading the [Don't Block the Event Loop](https://nodejs.org/en/learn/asynchronous-work/dont-block-the-event-loop) guide from Node.js for common patterns that can cause this.
+
+If you are doing a continuous CPU-heavy task, then we recommend you try using our `heartbeats.yield` function to automatically yield to the event loop periodically:
+
+```ts
+import { heartbeats } from "@trigger.dev/sdk";
+
+// code inside your task
+for (const row of bigDataset) {
+  await heartbeats.yield(); // safe to call every iteration, we will only actually yield when we need to
+  process(row); // this is a synchronous operation
+}
+```
+
+<Note>
+
+You could also offload the CPU-heavy work to a Node.js worker thread, but this is more complex to setup currently. We are planning on adding support for this in the future.
+
+</Note>
+
+If the above doesn't work, then we recommend you try increasing the machine size of your task. See our [machines guide](/machines) for more information.
+
+### Uncaught exceptions
+
+If you see a `TASK_RUN_UNCAUGHT_EXCEPTION` error, an exception escaped your task's `run()` function without being thrown through your `await` chain — the runtime caught it via Node's `process.on("uncaughtException")` handler. The dashboard surfaces this as a regular task failure (status `Failed`) and the run will retry according to your task's retry policy, but the exception still indicates a bug worth fixing.
+
+The most common cause is a Node `EventEmitter` emitting an `"error"` event with no listener attached. When this happens, Node escalates the event into an `uncaughtException`. Long-lived clients like `node-redis`, `pg`, `kafkajs`, and `mongodb` all surface socket-level errors this way.
+
+For example, a `node-redis` client with no error listener will fail your run with an `Error: read ECONNRESET` (or similar TCP error) the next time the socket is reset:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+import { createClient } from "redis";
+
+export const myTask = task({
+  id: "my-task",
+  run: async () => {
+    const client = createClient({ url: process.env.REDIS_URL });
+
+    // BAD: no .on("error", ...) listener — a socket reset will crash the run
+    // with an uncaught exception, even if the next .get() would have worked.
+    await client.connect();
+    return await client.get("foo");
+  },
+});
+```
+
+Fix it by attaching an `error` listener so the event has somewhere to go:
+
+```ts
+const client = createClient({ url: process.env.REDIS_URL });
+
+// GOOD: the listener catches socket-level errors. The awaited command
+// (e.g. .get) will still reject if the connection is broken, and that
+// rejection propagates through your run() and fails the attempt cleanly.
+client.on("error", (err) => {
+  logger.warn("Redis client error", { err });
+});
+
+await client.connect();
+return await client.get("foo");
+```
+
+The same fix applies to any library that emits `"error"` events. As a rule, attach an `.on("error", ...)` listener to every long-lived client you create inside a task.
+
+<Note>
+
+Unhandled promise rejections (e.g. `Promise.reject(...)` with no `.catch`) take the same path — Node routes them through `uncaughtException` by default, and the runtime treats them as `TASK_RUN_UNCAUGHT_EXCEPTION` for the same reasons. Make sure every promise either gets `await`ed or has a `.catch(...)` handler.
+
+</Note>
+
+### Realtime stream error (`sendBatchNonBlocking` / `S2AppendSession`)
+
+Errors mentioning `sendBatchNonBlocking`, `@s2-dev/streamstore`, or `S2AppendSession` (often with `code: undefined`) can occur when you close a stream and then await `waitUntilComplete()`, or when a stream runs for a long time (e.g. 20+ minutes). Wrap `waitUntilComplete()` in try/catch so Transport/closed-stream errors don't fail your task:
+
+```ts
+import { streams } from "@trigger.dev/sdk";
+
+const { waitUntilComplete } = streams.pipe("my-stream", dataStream); // or streams.writer(...)
+try {
+  await waitUntilComplete();
+} catch (err) {
+  // Transport/closed-stream; log if needed or ignore
+}
+```
+
+Alternatively, await `waitUntilComplete()` before closing the stream. See [Realtime Streams](/tasks/streams) for more.
+
+## Framework specific issues
+
+### NestJS swallows all errors/exceptions
+
+If you're using NestJS and you add code like this into your tasks you will prevent any errors from being surfaced:
+
+```ts
+export const simplestTask = task({
+  id: "nestjs-example",
+  run: async (payload) => {
+    //by doing this you're swallowing any errors
+    const app = await NestFactory.createApplicationContext(AppModule);
+    await app.init();
+
+    //etc...
+  },
+});
+```
+
+NestJS has a global exception filter that catches all errors and swallows them, so we can't receive them. Our current recommendation is to not use NestJS inside your tasks. If you're a NestJS user you can still use Trigger.dev but just don't use NestJS inside your tasks like this.
+
+### React is not defined
+
+If you see this error:
+
+```
+Worker failed to start ReferenceError: React is not defined
+```
+
+Either add this to your file:
+
+```ts
+import React from "react";
+```
+
+Or change the tsconfig jsx setting:
+
+```json
+{
+  "compilerOptions": {
+    //...
+    "jsx": "react-jsx"
+  }
+}
+```
+
+<NextjsTroubleshootingMissingApiKey />
+<NextjsTroubleshootingButtonSyntax />

package/docs/upgrading-packages.mdx

@@ -0,0 +1,80 @@
+---
+title: "How to upgrade the Trigger.dev packages"
+sidebarTitle: "Upgrading packages"
+description: "When we release fixes and new features we recommend you upgrade your Trigger.dev packages."
+---
+
+## Update command
+
+Run this command in your project:
+
+```sh
+npx trigger.dev@latest update
+```
+
+This will update all of the Trigger.dev packages in your project to the latest version.
+
+## Running the CLI locally
+
+When you run the CLI locally use the latest version for the `dev` and `deploy` commands:
+
+```sh
+npx trigger.dev@latest dev
+```
+
+```sh
+npx trigger.dev@latest deploy
+```
+
+These commands will also give you the option to upgrade if you are behind on versions.
+
+## Deploying with GitHub Actions
+
+You can deploy using [GitHub Actions](/github-actions). We recommend that you lock your version in the workflow file so make sure to upgrade.
+
+<Warning>
+  The deploy step will fail if version mismatches are detected. It's important that you update the
+  version using the steps below.
+</Warning>
+
+<Steps>
+  <Step title="Find your workflow file">
+    In your `.github/workflows` folder you can find your workflow yml files. You may have a prod
+    and staging one.
+  </Step>
+  <Step title="Update the version for the run command">
+    In the steps you'll see a `run` command. It will run the trigger.dev deploy CLI command. Make
+    sure to update this version to the latest version (e.g. `npx trigger.dev@4.7.3 deploy`).
+  </Step>
+</Steps>
+
+## package.json dev dependency
+
+Instead of using `npx`, `pnpm dlx` or `yarn dlx` you can add the Trigger.dev CLI as a dev dependency to your package.json file.
+
+For example:
+
+```json
+{
+  "devDependencies": {
+    "trigger.dev": "4.7.3"
+  }
+}
+```
+
+If you've done this make sure to update the version to match the `@trigger.dev/sdk` package.
+
+Once you have added the `trigger.dev` package to your `devDependencies`, you can use `npm exec trigger.dev`, `pnpm exec trigger.dev`, or `yarn exec trigger.dev` to run the CLI.
+
+But we recommend adding your dev and deploy commands to the `scripts` section of your `package.json` file:
+
+```json
+{
+  "scripts": {
+    "dev:trigger": "trigger dev",
+    "deploy:trigger": "trigger deploy"
+  }
+}
+```
+
+Then you can run `npm run dev:trigger` and `npm run deploy:trigger` to run the CLI.