ArmoHotspot/backend/.agents/skills/prisma-compute/references/troubleshooting.md

Troubleshooting Prisma Compute

Use this reference when setup, build, deploy, env, or runtime behavior fails.

First Checks

Run:

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:

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/=.*/=<redacted>/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:

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:

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:

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:

--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:

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:

bunx @prisma/cli@latest auth workspace use <workspace-id>
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 <id-or-name> 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 <workspace-id>.

To remove only one local OAuth workspace session:

bunx @prisma/cli@latest auth workspace logout <workspace-id-or-name>
# or:
bunx @prisma/cli@latest auth logout --workspace <workspace-id-or-name>

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:

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:

bunx @prisma/cli@latest app deploy --project <id-or-name> --json --no-interactive
bunx @prisma/cli@latest app deploy --create-project <name> --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:

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:

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 <deployment-id> --json

Fix:

• pass the same --branch <git-name> 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 <deployment-id>
• app show, app list-deploys, and app logs do not filter by branch; capture and use the deployment id
• treat app promote <deployment-id> 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 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:

Next.js build did not produce standalone output

Fix next.config.ts:

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:

.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:

Entrypoint is required
Entrypoint file does not exist

Fix either:

{
  "main": "src/index.ts"
}

or deploy with:

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 <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:

curl -i https://<deployment-url>
curl -i https://<deployment-url>/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:<deployed-http-port>

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:

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:

bunx @prisma/cli@latest app logs

Specific deployment:

bunx @prisma/cli@latest app logs --deployment <deployment-id>

Machine-readable:

bunx @prisma/cli@latest app logs --json

Build logs for GitHub/Console builds:

bunx @prisma/cli@latest build logs <build-id>
bunx @prisma/cli@latest build logs <build-id> --follow
bunx @prisma/cli@latest build logs <build-id> --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:

bunx @prisma/cli@latest feedback "app deploy crashed: <first error line>"

Prefer the pre-filled command from a --json crash envelope's nextActions verbatim. Anonymous; never put secrets, connection URLs, or tokens in the message.