Troubleshoot Deployment
A blocked deployment reports the condition that needs attention. Start with its first error; rerunning the same command cannot repair a missing credential or a conflicting schema.
Check the Remote Database
Inspect status without deploying:
pnpm exec cloudconfig db status --remote
- Pending migrations: local migrations have not been applied. Review and commit the files; deployment applies the pending migrations.
- Drift: the live database differs from the expected schema. Restore the expected schema before retrying.
- Tamper: an applied migration was renamed or removed locally. Restore the original file from version control.
The command follows the configured remote database, whether D1 or libSQL.
Resolve a Missing Secret
Supply the variable named in the error through the ignored .env file or
process environment. cloudconfig auth status and cloudconfig connect status
show configuration-specific variable names.
For Vercel or Azure with D1, check that the persistent token allows D1 Edit on the database's account. A working local Wrangler login alone is not enough for the deployed application.
Check the Host Account
For Vercel, run pnpm exec vercel whoami. Complete CLI authentication if it does
not return the expected account.
For Azure, run az account list --output table. A tenant-only login cannot deploy
an App Service: select an active subscription with the required permissions and
regional quota.
Check an App That Uploaded but Fails
Open the production alias printed for Vercel. A generated deployment URL may require a Vercel login even when the production alias is public.
On Azure, inspect App Service → Log stream and Deployment Center → Logs. Check startup errors and runtime data credentials. A successful upload does not verify that the app can query its database.
Retry After a Publish Failure
Deployment can apply migrations before publication fails. Fix the host issue and deploy again; those database changes remain applied.
Switching back to an older build does not undo SQL migrations. Keep schema changes compatible with both versions during a host transition.
--skip-build requires existing output built for the selected host. Deployment
still validates and packages that output before migrations.