# Troubleshooting Prisma Compute Use this reference when setup, build, deploy, env, or runtime behavior fails. ## First Checks Run: ```bash bunx @prisma/cli@latest --help bunx @prisma/cli@latest app deploy --help bunx @prisma/cli@latest auth whoami bunx @prisma/cli@latest auth workspace list --json ``` Then inspect: ```bash pwd cat package.json find .. -maxdepth 3 $ -name 'prisma.compute.ts' -o -name 'prisma.compute.mts' -o -name 'prisma.compute.js' -o -name 'prisma.compute.mjs' -o -name 'prisma.compute.cjs' $ -print test -f .env && sed -n 's/=.*/=/p' .env ``` Do not print unredacted secrets. ## `prisma.compute.ts` Not Picked Up This only matters when the project is supposed to use a config-backed deploy. A simple app without `prisma.compute.ts` can still deploy with explicit `app deploy` flags. Symptoms: - deploy ignores the expected framework, entrypoint, port, env file, or app root - a monorepo target such as `api` is not recognized - local state appears in the wrong `.prisma/` directory Check: ```bash pwd find .. -maxdepth 4 $ -name 'prisma.compute.ts' -o -name 'prisma.compute.mts' -o -name 'prisma.compute.js' -o -name 'prisma.compute.mjs' -o -name 'prisma.compute.cjs' $ -print bunx @prisma/cli@latest app deploy --help ``` Fix: - keep exactly one compute config file in the directory where it lives - put repo-wide or monorepo config at the repository/workspace root - run commands from inside the repo or workspace boundary so discovery can walk up to the config - use `[app]` targets from the `apps` keys, such as `bunx @prisma/cli@latest app deploy api` - remember that config-relative paths such as `root` and `env.file` resolve from the config file directory ## Compute Config Invalid Symptoms: - `COMPUTE_CONFIG_INVALID` - `COMPUTE_CONFIG_TARGET_REQUIRED` - `COMPUTE_CONFIG_TARGET_UNKNOWN` - "Multiple compute config files found" Fix: - export `defineComputeConfig({ app: ... })` or `defineComputeConfig({ apps: ... })` - define exactly one of `app` or `apps` - remove unknown top-level keys - pass a target for multi-app build/run commands, such as `app build web` - pass an existing `apps` key for multi-app deploys, such as `app deploy api` - for `nuxt`, `astro`, and `nestjs`, prefer strategy defaults unless a custom `build` override is intentional; current configs allow the override - for `framework: "custom"`, set both `build.outputDirectory` and `build.entrypoint` - when `build.outputDirectory` is set for a configurable framework, also set `build.entrypoint` if the framework needs a configured runtime entrypoint Minimal recovery config: ```typescript import { defineComputeConfig } from "@prisma/compute-sdk/config"; export default defineComputeConfig({ app: { framework: "hono", entry: "src/index.ts", httpPort: 8080, }, }); ``` ## `create-prisma --yes` Did Not Deploy `--yes` skips prompts and does not opt into deploy. Pass `--deploy` explicitly: ```bash bunx create-prisma@latest --name my-api --template hono --provider postgresql --deploy ``` If the integrated deploy cannot complete, scaffold succeeds but deploy should be reported as failed. ## Accidental Prisma Postgres Provisioning With PostgreSQL, no `--database-url`, and no `--no-prisma-postgres`, setup can provision Prisma Postgres. For local smoke tests, pass: ```bash --no-prisma-postgres --database-url "postgresql://USER:PASSWORD@HOST:PORT/DB" ``` Use a disposable real database URL if Prisma commands need to run. ## Auth Fails Symptoms: - `project list` fails - `auth whoami` fails - browser login was not completed - commands use the wrong workspace after a second login - another workspace is stored locally but commands behave signed out - `PRISMA_SERVICE_TOKEN` is missing, empty, expired, or lacks workspace/project permissions Fix: ```bash bunx @prisma/cli@latest auth login bunx @prisma/cli@latest auth whoami bunx @prisma/cli@latest auth workspace list --json ``` If multiple local OAuth workspaces exist, switch explicitly. Prefer ids from JSON: ```bash bunx @prisma/cli@latest auth workspace use bunx @prisma/cli@latest auth whoami --json bunx @prisma/cli@latest project list --json ``` For a human terminal, `auth workspace use` with no argument opens an interactive picker or selects the only local OAuth workspace without prompting. In non-interactive or `--json` mode, use `auth workspace use ` instead. If the active workspace was logged out or its token refresh failed, the CLI intentionally stays signed out for OAuth commands rather than falling through to another cached workspace. Recover by running `auth workspace list --json` and then `auth workspace use `. To remove only one local OAuth workspace session: ```bash bunx @prisma/cli@latest auth workspace logout # or: bunx @prisma/cli@latest auth logout --workspace ``` Use plain `auth logout` only when you want to clear all local OAuth workspace sessions. For CI, `@prisma/cli` can authenticate with `PRISMA_SERVICE_TOKEN`: ```bash test -n "${PRISMA_SERVICE_TOKEN:-}" && echo "PRISMA_SERVICE_TOKEN is set" bunx @prisma/cli@latest auth whoami bunx @prisma/cli@latest app deploy --json --no-interactive --prod --yes --env .env ``` If `PRISMA_SERVICE_TOKEN` is set and non-empty, it is the active auth source and local OAuth workspace switching is unavailable for command execution. Unset `PRISMA_SERVICE_TOKEN` before using `auth workspace use` to change local OAuth workspace context. If `PRISMA_SERVICE_TOKEN` is set but empty, the CLI errors before trying browser-login credentials. Unset it or provide a valid workspace service token. Never echo, log, or paste the token value; only check whether it is present. Local storage hints for debugging: - Override auth storage with `PRISMA_COMPUTE_AUTH_FILE` when isolating tests. - Default macOS OAuth credential file: `~/Library/Application Support/prisma/auth.json`. - Active workspace metadata sidecar: `~/Library/Application Support/prisma/auth.context.json`. - Project binding: `.prisma/local.json`. - Local app/project state: `.prisma/cli/state.json`, usually next to the discovered `prisma.compute.ts`. Do not print credential files or token values into logs. ## Project Setup Fails Symptoms: - `PROJECT_SETUP_REQUIRED` - non-interactive deploy cannot choose a Project - deploy was expected to create a Project but did not Fix: ```bash bunx @prisma/cli@latest app deploy --project --json --no-interactive bunx @prisma/cli@latest app deploy --create-project --yes ``` Do not rely on `--yes` alone to choose Project scope. `--project`, `--create-project`, and `PRISMA_PROJECT_ID` are mutually exclusive. ## Missing or Placeholder `DATABASE_URL` Symptoms: - Prisma Client throws `DATABASE_URL is required` - migration scripts fail immediately - deploy runs but app fails on database access Fix: 1. Put a real production-ready `DATABASE_URL` in `.env` or project env. 2. Run `prisma generate`. 3. Run migrations with the project's `db:migrate` or production migration command. 4. Redeploy with `--env .env` or project env configured. If Prisma Client generation or runtime env loading is the concrete failure, then inspect Prisma-specific config: ```bash test -f prisma.config.ts && sed -n '1,160p' prisma.config.ts test -f prisma/schema.prisma && sed -n '1,220p' prisma/schema.prisma ``` Never deploy `postgresql://USER:PASSWORD@HOST:PORT/DATABASE` placeholder values. ## Wrong Branch, Env, or Database Symptoms: - preview deploy reads production env - branch deploy cannot find `DATABASE_URL` - app is deployed to the expected branch but points at the wrong database - logs are inspected for the current app while the failing URL belongs to a different deployment id Check: ```bash bunx @prisma/cli@latest project show --json bunx @prisma/cli@latest project env list --role production --json bunx @prisma/cli@latest project env list --role preview --json bunx @prisma/cli@latest project env list --branch feature/foo --json bunx @prisma/cli@latest app list-deploys --json bunx @prisma/cli@latest app logs --deployment --json ``` Fix: - pass the same `--branch ` to `app deploy`, `database create`, and branch-specific `project env` commands - use `--role production` for production env and `--role preview` for preview-template env - capture the deployment id and URL from deploy JSON, then inspect logs with `app logs --deployment ` - `app show`, `app list-deploys`, and `app logs` do not filter by branch; capture and use the deployment id - treat `app promote ` as a production action because it rebuilds with production env vars - do not expect `prisma.compute.ts` to select Project, Branch, production, or database scope; it only supplies app deploy defaults ## Database Wiring or Schema Did Not Apply Symptoms: - deploy runs but the app cannot find `DATABASE_URL` - database env vars exist but the database is empty - a deploy-all run points multiple apps at the same branch database Fix: - read [`app-deploy-cli.md`](app-deploy-cli.md) `Database and Env` for the database/env guardrails - create and assign database env vars explicitly for the intended branch/app scope - run migrations, seed, or schema push yourself after database setup; Compute never applies schema changes for you - for multi-app deploy-all with app-specific database isolation, create and assign those database env vars explicitly before deploy ## Workspace plan limit reached When the installed CLI returns `PLAN_LIMIT_REACHED`, treat it as a workspace plan restriction rather than a Compute or database outage. For agent/CI handling, run the relevant database command with `--json` and branch on `error.code === "PLAN_LIMIT_REACHED"`. Read `error.meta.upgradeUrl`, `planName`, `workspaceId`, and `usageBlocked`; optional values may be `null`. This is a workspace plan restriction rather than a Compute/database outage. Use the canonical upgrade URL when returned or direct the user to Prisma Console. Do not retry as an outage or infer a plan limit from status codes or message text. ## Next.js Standalone Missing Error shape: ```text Next.js build did not produce standalone output ``` Fix `next.config.ts`: ```typescript const nextConfig = { output: "standalone", } export default nextConfig ``` Then reinstall/build if needed and deploy again. ## Next.js dependency missing after a successful build Symptoms in pnpm/Bun isolated workspaces can include a deployment that builds successfully but exits before useful runtime logs, often with `Cannot find module` for `styled-jsx` or another traced dependency. The current Compute SDK preserves in-artifact package-store symlinks and materializes only safe out-of-tree targets when staging Next standalone output. Do not manually flatten or rewrite `.next/standalone/node_modules` symlinks; that can break the isolated-store layout. Fix: 1. Upgrade `@prisma/compute-sdk` and `@prisma/cli` to current versions. 2. Remove only the generated build artifact/cache appropriate to the project, then rebuild. 3. Confirm `output: "standalone"`, redeploy, and inspect the new deployment logs. 4. If it persists, report the package manager, workspace layout, first missing module, and SDK/CLI versions through `@prisma/cli feedback` without secrets. ## Nitro Entry Missing Nuxt or TanStack Start error shape: ```text .output/server/index.mjs ``` General fix: - ensure the correct framework plugins are installed - run the framework build locally - avoid custom Nitro presets that produce a non-Node target - use the default Nitro node server preset For TanStack Start specifically: - keep `nitro` in `dependencies` - keep `import { nitro } from "nitro/vite"` in `vite.config.ts` - keep `plugins: [tanstackStart(), nitro(), viteReact()]` or the framework-equivalent plugin order - run `bun run build` and verify `.output/server/index.mjs` exists - do not replace the production server with `vite preview` Compute detection selects TanStack Start when it sees `@tanstack/react-start` or `@tanstack/solid-start`. If the Nitro entrypoint is missing after that, fix the TanStack/Nitro build output; do not assume Compute will silently use a Bun deployment. ## Bun Entrypoint Missing Error shape: ```text Entrypoint is required Entrypoint file does not exist ``` Fix either: ```json { "main": "src/index.ts" } ``` or deploy with: ```bash bunx @prisma/cli@latest app deploy --framework bun --entry src/index.ts ``` ## Port Mismatch Symptoms: - deploy succeeds but the app is unreachable - health checks fail - logs show the server listening on a different port Fix: - read `process.env.PORT` - pass `--http-port ` when the app has a fixed port - use the generated `compute:deploy` script when it exists - remember the `@prisma/cli app deploy` default is HTTP `3000`; generated Hono/Elysia projects usually configure `8080` through `prisma.compute.ts` or flag-backed `--http-port 8080` scripts - use the template defaults: Hono/Elysia `8080`, Next/TanStack/Nuxt `3000`, Astro `4321` ## Public URL Smoke Test Fails Symptoms: - deploy command completed - `app show` or deploy output has a URL - the public URL times out, returns 5xx, or returns an unexpected page Check: ```bash curl -i https:// curl -i https:///health bunx @prisma/cli@latest app logs --json ``` Fix by following the first concrete failure: - connection timeout or 5xx: check logs, host binding, and port mapping - unexpected status or body: verify the route path and app framework output - local URL tested by mistake: rerun against the public deployment URL, not `localhost` or `127.0.0.1` ## Localhost Binding Symptoms: - deploy says the app started or the port was observed, but the public URL is unreachable - logs show a server listening on `localhost` or `127.0.0.1` - `app run` works locally, but the deployed app cannot receive external traffic Why this happens: Compute's boot watcher polls `/proc/net/tcp` and `/proc/net/tcp6` for configured ports entering `LISTEN`. That readiness signal tracks the port, not whether the app bound `127.0.0.1` or all interfaces. A loopback-only listener can therefore look ready while public ingress still cannot reach it. Fix: - remove hard-coded `localhost` or `127.0.0.1` server host settings - bind on `0.0.0.0` or the framework equivalent, such as Astro `server.host: true` - for Next.js standalone, do not deploy with `HOSTNAME=localhost`; use `HOSTNAME=0.0.0.0` if the host is overridden - keep port and host fixes together: `0.0.0.0:` ## Env Changes Did Not Apply Generated `compute:deploy` scripts redeploy using the generated flags and/or `prisma.compute.ts`; they do not run migrations or seed data. After env changes: ```bash bunx @prisma/cli@latest project env list bunx @prisma/cli@latest project env list --branch feature/foo bunx @prisma/cli@latest app deploy --prod --yes --env .env bunx @prisma/cli@latest app deploy --branch feature/foo --env .env.preview ``` If using branch-specific env, confirm the branch name and role. ## Need Logs Runtime logs for the current app: ```bash bunx @prisma/cli@latest app logs ``` Specific deployment: ```bash bunx @prisma/cli@latest app logs --deployment ``` Machine-readable: ```bash bunx @prisma/cli@latest app logs --json ``` Build logs for GitHub/Console builds: ```bash bunx @prisma/cli@latest build logs bunx @prisma/cli@latest build logs --follow bunx @prisma/cli@latest build logs --json ``` Use `build logs` for build output keyed by a Build id from a GitHub check run, Console build page, or Management API build record. Use `app logs` for runtime logs keyed by the current app deployment or a deployment id. Summarize relevant errors. Do not paste secrets. ## Report Unresolved CLI Issues When a CLI failure survives the checks above, or a command crashes with `UNEXPECTED_ERROR`, report it to the Prisma team: ```bash bunx @prisma/cli@latest feedback "app deploy crashed: " ``` Prefer the pre-filled command from a `--json` crash envelope's `nextActions` verbatim. Anonymous; never put secrets, connection URLs, or tokens in the message.