Prisma ORM 8 is here.Read the docs

Domains

Open in ChatGPT

Point a custom domain at a production app and the platform verifies DNS and provisions TLS for you.

Configure custom domains that point to your production app. You can't configure custom domains for preview apps.

Before you start

You'll need:

Domain commands target the production branch. Pointing them at any other branch fails with a BRANCH_NOT_DEPLOYABLE error. Every domain subcommand also accepts --project and --branch flags.

Add a custom domain

1. Add a domain

bunx prisma service domain add shop.acme.com --service web

Registration verifies DNS up front. If the CNAME record isn't visible yet, the command fails with a DOMAIN_DNS_NOT_CONFIGURED error and prints the record name and value for you to create. Re-running add for a hostname that's already attached is safe: it shows the existing domain instead of failing.

2. Create CNAME Record

Add the printed DNS record, which points at switchboard.{region}.prisma.build.

Example:

TypeNameValueTTL
CNAMEshop.acme.comswitchboard.cdg.prisma.build300

The CLI prints the record name as the full hostname. If your DNS provider expects a relative name, enter just the label (shop).

3. Re-run add, then wait for provisioning

Once the CNAME record has propagated, re-run service domain add. This time registration succeeds and TLS provisioning starts. Track it with:

bunx prisma service domain wait shop.acme.com --service web

wait polls until the domain is active, up to 15 minutes. For a single status check, use --timeout 0:

bunx prisma service domain wait shop.acme.com --service web --timeout 0 --json

A single check exits non-zero with DOMAIN_VERIFICATION_TIMEOUT while the domain is still provisioning, so automation should read the status event rather than the exit code. In --json mode, wait streams newline-delimited status events, so an agent can track provisioning as it progresses.

Remove a domain

bunx prisma service domain remove shop.acme.com --service web

Removing detaches the domain from the app. Pass --yes to skip the confirmation prompt. Prisma can't touch your DNS, so the CNAME record stays behind. Delete it at your provider once you no longer need it.

States

A domain moves through these states:

StatusMeaning
pending_dnsThe domain is registered; TLS provisioning hasn't started yet
provisioning_tlsThe TLS certificate is being issued
activeThe domain is fully provisioned and routing traffic to your app
failedRegistration or provisioning failed; see the failure reason

Limits

  • Custom domains are only available on production apps.
  • DNS uses CNAME records only. Apex domains need a DNS provider that supports CNAME-like records (ALIAS, ANAME, or CNAME flattening) at the apex.
  • Wildcard hostnames such as *.acme.com are rejected.
  • Up to 3 custom domains per app. Adding more returns DOMAIN_QUOTA_EXCEEDED.
  • There's no workspace-wide domain list in the CLI.

Troubleshooting

bunx prisma service domain show shop.acme.com --service web
bunx prisma service domain retry shop.acme.com --service web

show prints the exact state, certificate details, and any DNS hints. retry restarts stuck provisioning. If a domain isn't in a retryable state, it returns DOMAIN_RETRY_NOT_ELIGIBLE.

Next steps

On this page