fix(webapp,cli): reject native builds server-side when base images are set

Native builds and local bundles cannot apply the instance's base images and never declared support, so the server was rejecting them with the message meant for outdated CLIs. Reject them with their own message on the server and drop the CLI-side checks that could never run.

Docs: describe what the build stage uses without a build image entry, note that --from-bundle rewrites the Containerfile inside the bundle directory, and shorten the env table rows.

Author: nicktrn

apps/webapp/app/v3/services/initializeDeployment.server.ts

@@ -148,13 +148,19 @@ export class InitializeDeploymentService extends BaseService {
         throw new ServiceValidationError("UNMANAGED deployments are not supported");
       }
 
-      if (
-        resolveDeployBaseImages(runtime, {
-          base: env.DEPLOY_BASE_IMAGES,
-          buildBase: env.DEPLOY_BUILD_BASE_IMAGES,
-        }) &&
-        payload.supportsInstanceBaseImages !== true
-      ) {
+      const requiredBaseImages = resolveDeployBaseImages(runtime, {
+        base: env.DEPLOY_BASE_IMAGES,
+        buildBase: env.DEPLOY_BUILD_BASE_IMAGES,
+      });
+
+      if (requiredBaseImages && payload.isNativeBuild) {
+        throw new ServiceValidationError(
+          "This instance requires custom deploy base images, which native builds cannot apply. Deploy without --native-build or --local-bundle.",
+          400
+        );
+      }
+
+      if (requiredBaseImages && payload.supportsInstanceBaseImages !== true) {
         throw new ServiceValidationError(
           "This instance requires custom deploy base images, which this version of the CLI cannot apply. Upgrade the trigger.dev CLI and deploy again.",
           400

docs/self-hosting/env/webapp.mdx

@@ -97,8 +97,8 @@ mode: "wide"
 | `DEPLOY_REGISTRY_NAMESPACE`                      | No       | trigger               | Deploy registry namespace.                                                                                         |
 | `DEPLOY_REGISTRY_ECR_DEFAULT_REPOSITORY_POLICY`  | No       | —                     | Raw IAM policy JSON applied via SetRepositoryPolicy to every ECR repo created by the webapp. Use to grant cross-account pull access to EKS workers when the ECR account is separate from the cluster account. |
 | `DEPLOY_IMAGE_PLATFORM`                          | No       | linux/amd64           | Deploy image platform, same values as docker `--platform` flag.                                                    |
-| `DEPLOY_BASE_IMAGES`                             | No       | —                     | Base images every deploy must build on. Comma-separated `runtime=image@sha256:<digest>` entries, e.g. `node-26=registry.example.com/node-fips:26@sha256:...`. Runtimes: `node-22`, `node-24`, `node-26`, `bun`. The digest is required. Projects with `runtime: "node"` resolve to the current default Node runtime (`node-24` today), so set that key for them. Deploys from CLI versions that cannot apply the images are rejected with an upgrade message, and deploys using `--native-build` or `--local-bundle` fail when base images are configured. An invalid value prevents the webapp from starting. See [custom base images](/self-hosting/overview#custom-base-images). |
-| `DEPLOY_BUILD_BASE_IMAGES`                       | No       | —                     | Build-stage images per runtime. Same format and validation as `DEPLOY_BASE_IMAGES`. Defaults to the published `-build` images. |
+| `DEPLOY_BASE_IMAGES`                             | No       | —                     | Base images every deploy must build on. Comma-separated `runtime=image@sha256:<digest>` entries, e.g. `node-26=registry.example.com/node-fips:26@sha256:...`. Runtimes: `node-22`, `node-24`, `node-26`, `bun`. The digest is required. An invalid value prevents the webapp from starting. See [custom base images](/self-hosting/overview#custom-base-images). |
+| `DEPLOY_BUILD_BASE_IMAGES`                       | No       | —                     | Build-stage images per runtime, same format and validation. Without an entry the build stage uses the published build image, or the base image plus a toolchain install when build extensions add image instructions. |
 | `DEPLOY_TIMEOUT_MS`                              | No       | 480000 (8m)           | Deploy timeout (ms).                                                                                               |
 | `DEPLOY_QUEUE_TIMEOUT_MS`                        | No       | 900000 (15m)          | Deploy queue timeout (ms).                                                                                         |
 | **Object store (S3)**                            |          |                       |                                                                                                                    |

docs/self-hosting/overview.mdx

@@ -110,9 +110,9 @@ DEPLOY_BASE_IMAGES="node-26=registry.example.com/node-fips:26@sha256:<64-charact
 
 Entries are comma-separated `runtime=image@sha256:<digest>`. The runtimes are `node-22`, `node-24`, `node-26` and `bun`, and every image must be pinned by digest. An invalid value prevents the webapp from starting. With the Helm chart, set them through `webapp.extraEnvVars`.
 
-Projects with `runtime: "node"` in their config resolve to the current default Node runtime (`node-24` today), so set that key for them. Deploys from CLI versions that cannot apply the images are rejected with an error asking to upgrade. Deploys using `--native-build` or `--local-bundle` fail with an error when base images are configured, since those paths cannot apply them.
+Projects with `runtime: "node"` in their config resolve to the current default Node runtime (`node-24` today), so set that key for them. Deploys from CLI versions that cannot apply the images are rejected with an error asking to upgrade. Deploys using `--native-build` or `--local-bundle` are rejected when base images are configured, since those paths cannot apply them.
 
-The CLI builds with these images for any runtime that has an entry. Runtimes without one keep the published images. It applies to deploys built with the CLI's local build path, which is what self-hosted instances use. `--from-bundle` deploys regenerate the bundle's Containerfile with these images. This is a self-hosting setting and does not apply to Trigger.dev Cloud.
+The CLI builds with these images for any runtime that has an entry. Runtimes without one keep the published images. It applies to deploys built with the CLI's local build path, which is what self-hosted instances use. `--from-bundle` deploys regenerate the Containerfile inside the bundle directory with these images. This is a self-hosting setting and does not apply to Trigger.dev Cloud.
 
 You own a custom base image. A Node image must provide:
 
@@ -128,7 +128,7 @@ A Bun image must provide:
 - a `bun` user
 - glibc, so native modules built in the build stage load at runtime
 
-A `DEPLOY_BUILD_BASE_IMAGES` image must contain everything the base image provides, plus the toolchain the published build images include: `python3`, `make` and `g++`. When a project's build extensions add image instructions, those instructions are replayed on the build-stage image, so it must be able to run them. Without a `DEPLOY_BUILD_BASE_IMAGES` entry, the build stage is created from your base image and the toolchain is installed with `apt-get`, so the base image must be Debian-based for those projects.
+A `DEPLOY_BUILD_BASE_IMAGES` image must contain everything the base image provides, plus the toolchain the published build images include: `python3`, `make` and `g++`. When a project's build extensions add image instructions, those instructions are replayed on the build-stage image, so it must be able to run them. Without a `DEPLOY_BUILD_BASE_IMAGES` entry, the build stage uses the published build image. The exception is a project whose build extensions add image instructions: its build stage is created from your base image and the toolchain is installed with `apt-get`, so the base image must be Debian-based for those projects. To avoid the published build image entirely, set both `DEPLOY_BASE_IMAGES` and `DEPLOY_BUILD_BASE_IMAGES`.
 
 <Warning>
   `image.pkgs` and build extensions that run `apt-get` (such as `aptGet` and `playwright`) assume a

packages/cli-v3/src/commands/deploy.ts

@@ -1498,13 +1498,6 @@ async function handleNativeBuildServerDeploy({
 
   const deployment = initializeDeploymentResult.data;
 
-  if (deployment.baseImages) {
-    $deploymentSpinner.stop("Failed to initialize deployment");
-    throw new Error(
-      "This instance requires custom deploy base images, which cannot be applied with --native-build. Deploy without that flag."
-    );
-  }
-
   const rawDeploymentLink = `${dashboardUrl}/projects/v3/${config.project}/deployments/${deployment.shortCode}`;
   const rawTestLink = `${dashboardUrl}/projects/v3/${config.project}/test?environment=${
     options.env === "prod" ? "prod" : "stg"
@@ -1838,13 +1831,6 @@ async function handleLocalBundleDeploy({
 
   const deployment = initializeDeploymentResult.data;
 
-  if (deployment.baseImages) {
-    $deploymentSpinner.stop("Failed to initialize deployment");
-    throw new Error(
-      "This instance requires custom deploy base images, which cannot be applied with --local-bundle. Deploy without that flag."
-    );
-  }
-
   const rawDeploymentLink = `${dashboardUrl}/projects/v3/${config.project}/deployments/${deployment.shortCode}`;
   const rawTestLink = `${dashboardUrl}/projects/v3/${config.project}/test?environment=${
     options.env === "prod" ? "prod" : "stg"