@trigger.dev/sdk 4.6.4 → 4.7.1

package/docs/self-hosting/kubernetes.mdx

@@ -35,7 +35,13 @@ flowchart TD
   workers --> reg
 ```
 
-Each component maps to a top-level key in `values.yaml`: `webapp`, `supervisor`, `postgres`, `redis`, `electric`, `clickhouse`, `s3` (object storage), `s2`, and `registry`. The datastores default to `deploy: true` and run in-cluster; set `deploy: false` with an `external` block to bring your own. The registry is the exception - it defaults to `deploy: false`, so you point it at an external one. Webapp settings live under `webapp`, supervisor settings under `supervisor.config`, and each service takes `extraEnvVars` for anything else.
+Each component maps to a top-level key in `values.yaml`: `webapp`, `supervisor`, `postgres`, `redis`, `clickhouse`, `s3` (object storage), `s2`, and `registry`. The datastores default to `deploy: true` and run in-cluster; set `deploy: false` with an `external` block to bring your own. The registry is the exception - it defaults to `deploy: false`, so you point it at an external one. Webapp settings live under `webapp`, supervisor settings under `supervisor.config`, and each service takes `extraEnvVars` for anything else.
+
+Realtime run subscriptions use the native backend with the configured PostgreSQL, Redis, and ClickHouse services. The chart sets `REALTIME_BACKEND_NATIVE_ENABLED=1` and `REALTIME_BACKEND_DEFAULT=native`; no Electric service is required. These settings are separate from the S2-backed realtime streams configuration.
+
+<Warning>
+  Before upgrading from a chart that deploys Electric, unset the global `realtimeBackend` feature flag and any organization overrides, or set them to `native`. Both take precedence over the environment default. Values of `electric` or `shadow` still select the Electric backend, which this chart no longer deploys.
+</Warning>
 
 ## Requirements
 
@@ -91,7 +97,7 @@ Bundled datastores let you run the whole stack with a single command and no exte
       --create-namespace
     ```
 
-    The chart deploys the webapp, supervisor, and bundled Postgres, Redis, Electric, ClickHouse, MinIO, and s2-lite. The registry is not deployed by default - configure an external one before deploying tasks.
+    The chart deploys the webapp, supervisor, and bundled Postgres, Redis, ClickHouse, MinIO, and s2-lite. The registry is not deployed by default - configure an external one before deploying tasks.
   </Step>
 
   <Step title="Port-forward the webapp">
@@ -533,9 +539,14 @@ With external datastores, secrets, registry, and authentication in place, you ha
 
 ### Upgrading
 
-`helm upgrade` is safe to run as-is. Your generated secrets, data volumes, and the bundled ClickHouse are preserved and migrated automatically, so a normal upgrade needs no preparation. A few situations need one manual step first — expand any that apply to you.
+Your generated secrets, data volumes, and the bundled ClickHouse are preserved and migrated automatically. Before running `helm upgrade`, complete any prerequisites below that apply to your installation.
 
 <AccordionGroup>
+  <Accordion title="You upgrade from a chart that deploys Electric">
+    Unset the global `realtimeBackend` feature flag and any organization overrides, or set them to `native`, before upgrading. Organization overrides take precedence over the global flag, and the global flag takes precedence over `REALTIME_BACKEND_DEFAULT`.
+
+    The chart enables native realtime and removes the Electric service. A remaining `electric` or `shadow` flag value directs run subscriptions to that removed service and breaks realtime updates.
+  </Accordion>
   <Accordion title="You supply your own secret (secrets.existingSecret)">
     With `secrets.existingSecret` set, the chart reads every key from your Secret and generates none, so any key the app needs must already be present there.
 

package/docs/tasks/overview.mdx

@@ -98,16 +98,14 @@ For more information read [the retrying guide](/errors-retrying).
 
 It's also worth mentioning that you can [retry a block of code](/errors-retrying) inside your tasks as well.
 
-### `queue` options
+### `queue` and `concurrency` options
 
-Queues allow you to control the concurrency of your tasks. This allows you to have one-at-a-time execution and parallel executions. There are also more advanced techniques like having different concurrencies for different sets of your users. For more information read [the concurrency & queues guide](/queue-concurrency).
+Queues control the order your runs execute in, and concurrency limits control how many execute at once: one-at-a-time execution, parallel executions, and more advanced techniques like separate concurrency for different sets of your users. For more information read the [Queues](/queues) and [Concurrency](/concurrency) guides.
 
 ```ts /trigger/one-at-a-time.ts
 export const oneAtATime = task({
   id: "one-at-a-time",
-  queue: {
-    concurrencyLimit: 1,
-  },
+  concurrency: { total: 1 },
   run: async (payload: any, { ctx }) => {
     //...
   },

package/docs/troubleshooting-alerts.mdx

@@ -7,6 +7,14 @@ We support receiving alerts for the following events:
 - Run fails
 - Deployment fails
 - Deployment succeeds
+- A new error group appears, regresses, or is unignored
+
+The first three are created from the **Alerts** page. The fourth — an **Error group** alert — is created from the **Errors** page instead, but appears in the same Alerts table once created. It behaves quite differently from a run failure alert; see [Error group alerts](#error-group-alerts) below.
+
+<Note>
+  If you want to be told about **every** run that fails, choose a **run fails** alert. An Error group
+  alert will not do this — it deliberately stays quiet once it has alerted on a given error.
+</Note>
 
 ## How to setup alerts
 
@@ -36,6 +44,37 @@ Click on the triple dot menu on the right side of the table row and select "Disa
 </Steps>
 
 
+## Error group alerts
+
+Error group alerts are **issue-based**, not run-based. They are created from the **Errors** page in the dashboard (the "Configure alerts…" button), not from the New alert modal on the Alerts page. Once created they show up in the Alerts table alongside your other alerts, labelled "Error group".
+
+An error group is one distinct error — the same error from many runs is a single group, with a status of **Unresolved**, **Resolved** or **Ignored** that you set from the Errors page.
+
+### When an error group alert fires
+
+The alert only fires when a group's status *changes* in one of these three ways:
+
+| Trigger | Meaning |
+| :------ | :------ |
+| New issue | The error has been seen for the first time. |
+| Regression | The group was marked **Resolved**, and the error has occurred again since. |
+| Unignored | The group was **Ignored**, and the ignore condition you set has been breached. |
+
+### Why it goes quiet
+
+This is the part that surprises people, so it is worth stating plainly:
+
+**An Unresolved error group does not alert.** After an error group alert fires, the group is set to Unresolved, and it stays silent no matter how many more times that error occurs. It will only alert again once you mark it **Resolved** (and it then recurs) or **Ignored** (and the ignore condition is breached).
+
+This is intentional — one persistently broken task should not flood your Slack channel with a message per failed run. But it means an Error group alert is not a substitute for a run failure alert. If a task has been failing in production for days and you have had no notification, check whether the only alert you have configured is an Error group alert whose group is sitting at Unresolved.
+
+### Which alert type should I use?
+
+- **"Tell me about every run that fails"** → a **run fails** alert, from the Alerts page. It fires for every run that fails once its retries are exhausted.
+- **"Tell me when something new breaks"** → an **Error group** alert, from the Errors page.
+
+The two are complementary, and many teams want both.
+
 ## Alert webhooks
 
 For the alert webhooks you can use the SDK to parse them. Here is an example of how to parse the webhook payload in Remix:
@@ -69,6 +108,10 @@ export async function action({ request }: ActionFunctionArgs) {
         console.log("[Webhook Internal Test] Deployment failed alert webhook received", { event });
         break;
       }
+      case "alert.error": {
+        console.log("[Webhook Internal Test] Error group alert webhook received", { event });
+        break;
+      }
       default: {
         console.log("[Webhook Internal Test] Unhandled webhook type", { event });
       }
@@ -112,7 +155,7 @@ When you create a webhook alert, you'll receive different payloads depending on
 </ParamField>
 
 <ParamField path="type" type="string">
-  The type of alert webhook. One of: `alert.run.failed`, `alert.deployment.success`, or `alert.deployment.failed`
+  The type of alert webhook. One of: `alert.run.failed`, `alert.deployment.success`, `alert.deployment.failed`, or `alert.error`
 </ParamField>
 
 ### Run Failed Alert
@@ -383,3 +426,83 @@ This webhook is sent when a deployment fails. The payload is available on the `o
   Project name
 </ParamField>
 
+
+### Error Group Alert
+
+This webhook is sent for an [error group alert](#error-group-alerts). The payload is available on the `object` property:
+
+<ParamField path="object.classification" type="string">
+  Why the alert fired. One of: `new_issue`, `regression`, `unignored`
+</ParamField>
+
+<ParamField path="object.error.fingerprint" type="string">
+  Identifier for the error group
+</ParamField>
+
+<ParamField path="object.error.type" type="string">
+  Error type
+</ParamField>
+
+<ParamField path="object.error.message" type="string">
+  Error message
+</ParamField>
+
+<ParamField path="object.error.stackTrace" type="string">
+  Sample stack trace, if available
+</ParamField>
+
+<ParamField path="object.error.firstSeen" type="string">
+  When the error was first seen
+</ParamField>
+
+<ParamField path="object.error.lastSeen" type="string">
+  When the error was last seen
+</ParamField>
+
+<ParamField path="object.error.occurrenceCount" type="number">
+  Number of occurrences
+</ParamField>
+
+<ParamField path="object.error.taskIdentifier" type="string">
+  Task the error occurred in
+</ParamField>
+
+<ParamField path="object.environment.id" type="string">
+  Environment ID
+</ParamField>
+
+<ParamField path="object.environment.name" type="string">
+  Environment name
+</ParamField>
+
+<ParamField path="object.organization.id" type="string">
+  Organization ID
+</ParamField>
+
+<ParamField path="object.organization.slug" type="string">
+  Organization slug
+</ParamField>
+
+<ParamField path="object.organization.name" type="string">
+  Organization name
+</ParamField>
+
+<ParamField path="object.project.id" type="string">
+  Project ID
+</ParamField>
+
+<ParamField path="object.project.ref" type="string">
+  Project reference
+</ParamField>
+
+<ParamField path="object.project.slug" type="string">
+  Project slug
+</ParamField>
+
+<ParamField path="object.project.name" type="string">
+  Project name
+</ParamField>
+
+<ParamField path="object.dashboardUrl" type="string">
+  URL to view the error in the dashboard
+</ParamField>

package/docs/troubleshooting.mdx

@@ -163,6 +163,18 @@ You need to be on at least these minor versions:
 
 ## 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).

package/docs/vercel-integration.mdx

@@ -5,7 +5,7 @@ description: "Automatically deploy your tasks whenever you deploy to Vercel."
 
 ## How it works
 
-The Vercel integration connects your Vercel project to your Trigger.dev project so that every Vercel deployment automatically triggers a Trigger.dev deployment. It also syncs environment variables from Vercel into Trigger.dev, and sets up [version skew protection](/deployment/version-skew-protection) so your app and tasks stay in sync.
+The Vercel integration connects your Vercel project to your Trigger.dev project so that every Vercel deployment automatically triggers a Trigger.dev deployment. It also syncs environment variables from Vercel into Trigger.dev, and sets up [version skew protection](/deployment/atomic-deployment) so your app and tasks stay in sync.
 
 This eliminates the need to manually run the `trigger.dev deploy` command or maintain custom CI/CD workflows for Vercel-based projects.
 
@@ -121,7 +121,7 @@ If you use [Supabase Branching](https://supabase.com/docs/guides/deployment/bran
 
 ## Version skew protection
 
-Your Vercel app and your tasks are deployed separately, so there is always a window where a new app can trigger tasks built from older code. [Version skew protection](/deployment/version-skew-protection) closes that window: each Trigger.dev deployment is tagged with your commit SHA, your app sends the same SHA when it triggers, and every run is pinned to the deployment built from the same commit. Runs triggered before the task build finishes wait for it rather than running on the previous version.
+Your Vercel app and your tasks are deployed separately, so there is always a window where a new app can trigger tasks built from older code. [Version skew protection](/deployment/atomic-deployment) closes that window: each Trigger.dev deployment is tagged with your commit SHA, your app sends the same SHA when it triggers, and every run is pinned to the deployment built from the same commit. Runs triggered before the task build finishes wait for it rather than running on the previous version.
 
 The integration sets this up for you:
 
@@ -145,7 +145,7 @@ To opt out, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` on your Verce
 
 <Warning>
   **Automatic atomic deployments are deprecated.** Use [version skew
-  protection](/deployment/version-skew-protection) instead — it needs no second Vercel deployment,
+  protection](/deployment/atomic-deployment) instead — it needs no second Vercel deployment,
   never gates your app's deploy, doesn't touch `Auto-assign Custom Production Domains`, and covers
   staging and preview as well as production.
 
@@ -193,7 +193,7 @@ Atomic deployments are off by default for new connections. Projects that already
   that setting in Vercel or promote deployments yourself.
 </Note>
 
-Previously, setting up atomic deployments with Vercel required custom GitHub Actions workflows. The Vercel integration automates this entirely. For more details on how atomic deployments work, see [Atomic deploys](/deployment/atomic-deployment). For how to move off them, see [replacing automatic atomic deployments](/deployment/version-skew-protection#replacing-automatic-atomic-deployments).
+Previously, setting up atomic deployments with Vercel required custom GitHub Actions workflows. The Vercel integration automates this entirely. For how to move off them, see [legacy atomic deployments](/deployment/atomic-deployment#legacy-atomic-deployments).
 
 ## Environment mapping
 
@@ -217,7 +217,7 @@ If your Vercel project has a custom environment, you can select which one maps t
 
 You can configure the following settings per-environment from your project's Vercel settings:
 
-- **Atomic deployments** (deprecated): Controls whether Trigger.dev gates and redeploys your Vercel deployment to keep it in sync. Off by default for new connections — use [version skew protection](/deployment/version-skew-protection) instead.
+- **Atomic deployments** (deprecated): Controls whether Trigger.dev gates and redeploys your Vercel deployment to keep it in sync. Off by default for new connections — use [version skew protection](/deployment/atomic-deployment) instead.
 - **Pull env vars before build**: When enabled, Trigger.dev pulls the latest environment variables from Vercel before each build. Enabled for production, staging, and preview by default.
 - **Discover new env vars**: When enabled, new environment variables found in Vercel that don't yet exist in Trigger.dev are created automatically during builds. Only available for environments that also have env var pulling enabled. Enabled for production, staging, and preview by default.
 
@@ -234,8 +234,7 @@ Disconnecting stops automatic deployments, environment variable syncing, and dep
 
 ## Related
 
-- [Version skew protection](/deployment/version-skew-protection)
+- [Atomic deployments (version skew protection)](/deployment/atomic-deployment)
 - [GitHub integration](/github-integration)
-- [Atomic deploys](/deployment/atomic-deployment) (deprecated for Vercel)
 - [Environment variables](/deploy-environment-variables)
 - [Preview branches](/deployment/preview-branches)

package/docs/versioning.mdx

@@ -47,7 +47,7 @@ So a task run will continue running on the version it was locked to. We do this
 
 Every deployment creates a new version of all tasks for that environment.
 
-Because your application and your tasks deploy separately, a release of your app can briefly trigger tasks that belong to a different version. [Version skew protection](/deployment/version-skew-protection) pins each run to the deployment built from the same commit, once your app sends the id it was deployed with.
+Because your application and your tasks deploy separately, a release of your app can briefly trigger tasks that belong to a different version. [Version skew protection](/deployment/atomic-deployment) pins each run to the deployment built from the same commit, once your app sends the id it was deployed with.
 
 ## Retries and reattempts
 

package/docs/writing-tasks-introduction.mdx

@@ -15,7 +15,8 @@ Before digging deeper into the details of writing tasks, you should read the [fu
 | [Logging](/logging)                          | View and send logs and traces from your tasks.                                                      |
 | [Errors & retrying](/errors-retrying)        | How to deal with errors and write reliable tasks.                                                   |
 | [Wait](/wait)                                | Wait for periods of time or for external events to occur before continuing.                         |
-| [Concurrency & Queues](/queue-concurrency)   | Configure what you want to happen when there is more than one run at a time.                        |
+| [Queues](/queues)                            | Control the order your runs execute in.                                                             |
+| [Concurrency](/concurrency)                  | Limit how many runs execute at once: per task, per tenant, or shared across tasks.                  |
 | [Realtime notifications](/realtime/overview) | Send realtime notifications from your task that you can subscribe to from your backend or frontend. |
 | [Versioning](/versioning)                    | How versioning works.                                                                               |
 | [Machines](/machines)                        | Configure the CPU and RAM of the machine your task runs on                                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.6.4",
+  "version": "4.7.1",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -69,7 +69,7 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "4.6.4",
+    "@trigger.dev/core": "4.7.1",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {