Debug Deploy Failures · Prisma Compute · prisma/skills · Skills Docs

Debug Deploy Failures · Prisma Compute · prisma/skills · Skills Docs

Symptom	Cause	Fix
`CLI.UNKNOWN_COMMAND` for `app`, `build`, `database`, `agent`, `destroy`, `compute`	The command was removed	Use the replacement in the SKILL.md table
`Unknown command "auth"` or `"deploy"`, or `prisma dev` starts a database server	A Prisma 6 or 7 `prisma` binary	Install `prisma` 8.x as a dev dependency, or use `npx @prisma/cli@latest`
`ERR_UNKNOWN_FILE_EXTENSION`	Node.js too old to load `module.ts`. Composer supports 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer	Upgrade Node.js
`CLI.CONFIG_UNREADABLE` with a module error from `effect`	Another `effect` version hoisted over the one `@prisma/composer` pins	Match the app’s `effect` to `@prisma/composer`‘s `dependencies.effect`, or force it with `overrides` (npm), `pnpm.overrides` or `pnpm-workspace.yaml` `overrides` (pnpm), `resolutions` (Yarn); reinstall
`CLI.CONFIG_SECTION_INVALID` with `CONFIG.SECTION_MISSING`	No `composer` section in `prisma.config.ts`	Add the section (`app-composer-setup.md`)
`CONFIG.FILE_RETIRED` or `CONFIG.FIELD_RETIRED`	A `prisma-composer.config.ts` or `configPath` from an older Composer	Move `extensions` and `state` into the `composer` section and delete the old file
`ASSEMBLE.EXTENSION_MISSING`	A service uses `nextjs()` but `nextjsBuild()` is not in `extensions`	Add `nextjsBuild()` from `@prisma/composer/nextjs/control`
`COMPOSE.GRAPH_INVALID` naming an id	A provision id or service name with a hyphen or other non-alphanumeric character	Use `[A-Za-z0-9]` only; at least three characters for provision ids
Bun APIs fail while the CLI loads `module.ts`	The `prisma` bin runs under Node	`bun node_modules/.bin/prisma deploy module.ts`

Symptom	Cause	Fix
`CLI.CREDENTIALS_REQUIRED`	No session and no service token	Ask the user to run `npx prisma auth login`; in CI set `PRISMA_SERVICE_TOKEN` and `PRISMA_WORKSPACE_ID`
Error about a blank `PRISMA_SERVICE_TOKEN`	The variable is set but empty	Unset it or provide a token
Commands act in the wrong workspace	Another stored session is current, or a service token overrides it	`auth workspace list --json`, then `auth workspace use <id>`; unset `PRISMA_SERVICE_TOKEN` to use sessions
`PROJECT.SETUP_REQUIRED` after a successful deploy	`deploy` does not link the directory	`npx prisma project link <app-name>` or pass `--project`
`project "<name>" does not exist yet and no deploy region is configured`	First deploy without a region	`prismaCloud({ region })` or `PRISMA_REGION`
Deploy refuses an existing project name (`HostedStateBootstrapError`, or `a project with this name already exists`)	A project with the module’s name exists that this module did not create	`deploy --name <unique-name>`, or rename the module
Deploy fails immediately naming another holder	Another deploy of the same environment holds the state lease	Wait for it; a crashed deploy’s lease expires after about a minute

Symptom	Cause	Fix
`ASSEMBLE.BUILD_FAILED`	The built entry or directory is missing or invalid (no build, wrong path, symlinks in a `dir` build)	Run the build and check that `entry`/`dir` match its output, relative to `service.ts`
`ASSEMBLE.SERVICE_MISSING`	The module provisions no service	Provision at least one `compute()` service
`DEPLOY.STAGE_INVALID`	The stage is not a valid Git ref name	Rename the stage
A connection input “declares param …, but its producer … did not supply it”	An authored connection or extension does not supply a declared value	Fix the producer’s outputs; mark the param optional only if absent is valid
Deploy fails early naming a missing variable	An `envParam`/`envSecret` name is unset on the stage and in the shell	Export it in the deploying shell or set it with `project env add`
`MIGRATION_PATH_NOT_FOUND`	A `postgres(contract)` schema change has no committed migration	`prisma contract emit`, `prisma migration plan --name <slug>`, commit `migrations/`
`DEPLOY.ENGINE_FAILED`	The deploy engine or the platform rejected the generated stack	Read the engine lines in the error; it names `.prisma-composer/alchemy.run.ts` and a command that reproduces the failure
`DEPLOY.BUILD_REQUIRED` from `destroy`	`destroy` packages the built app too	Build, then destroy

Symptom	Cause	Fix
Public URL times out or returns 502 at once	Listener on `localhost`, wrong port, or a crash at boot	Bind `0.0.0.0` on `service.port()`; read `npx prisma service logs <service>`
`Cannot find package`, `Cannot find module`, or `ENOENT while resolving package` in logs	The build left a package as an import, and the default `dependencies: "bundled"` ships only the build output	Bundle every dependency (`bun build --target=bun`), or set `dependencies: "external"` on `node()` so the deploy stages the installed packages
502s in a loop after the app was idle	A database client dies when idle connections close	Small reconnect-friendly pool; log `uncaughtException` and `unhandledRejection` instead of exiting
`504 Gateway Time-out` with an `openresty` body after about 60 seconds	The handler sent nothing for 60 seconds	Respond first, continue under `waitUntil`, or queue the work
Background work stops or never finishes	The instance slept	`waitUntil` or `KeepAwakeGuard` from `@prisma/compute`; persist progress
`401` from a deployed `/rpc/<method>`	Composer’s service-key check; only wired consumers may call	Test through a consumer or locally; not a deploy failure
`RUNTIME.TEMPORAL_UNAVAILABLE` or a failure on the first timestamp read	No global `Temporal` on the runtime	Import a Temporal polyfill at the server entry, or use string column types
Next.js page shows build-time or missing values from `service.load()`	The route was prerendered	`export const dynamic = "force-dynamic"`
`ECONNRESET` calling another service	The callee was cold-starting	Retry
A changed env var has no effect	Values resolve at deploy time	Redeploy (or promote)
A resource disappeared after a deploy	Its `provision()` was removed from `module.ts`	Restore the declaration and redeploy
A preview’s database is empty	Stages get their own empty databases	Seed it; production data is never copied

Symptom	Cause	Fix
Push builds nothing, no error	No workflow on the pushed branch	Add `.github/workflows/prisma-deploy.yml` (`deploy-on-push.md`)
Green run with `skipped-no-credential`	Repository not connected, no `id-token: write`, or a fork	`npx prisma git connect`, add the permission
`CLI.UNKNOWN_COMMAND` inside the action	Action release v1.5.0 or older	Use `prisma/cloud-deploy-action@v1` (v1.9.0 or later)
Install step fails on pnpm or Yarn	The action auto-detects npm and Bun only	Set `install-command`