Debugging Failed Deployments

Varity Team Core Contributors Updated April 2026

When a deployment fails, the fastest path to recovery is: get the logs → identify the error → fix or rollback. This page walks through each step.

Step 1 — Get the Build Logs

Every deployment produces a build log. Always read it before guessing at a cause.

From the CLI (verbose mode)

Re-run the deploy with --verbose to stream full output:

varitykit app deploy --verbose

From a past deployment

If the deployment already ran, retrieve its logs by ID:

varitykit app info deploy-1737492000

From the MCP server

If you’re in an AI editor with the Varity MCP server connected:

"Show me the build logs for deploy-1737492000"

This calls varity_deploy_logs:

Parameter	Type	Required	Description
`deployment_id`	string	Yes	The deployment ID from `varitykit app list`
`limit`	number	No	Max log lines (default 100)

Common Error Patterns

”Build failed: exit code 1”

The build command (npm run build) failed.

Reproduce locally:
Terminal window
```
npm run build
```
Fix TypeScript or lint errors:
Terminal window
```
npx tsc --noEmit
```
Ensure all dependencies are installed:
Terminal window
```
npm install
```
Re-deploy:
Terminal window
```
varitykit app deploy
```

“Upload failed” / “Network timeout”

The build succeeded but the upload to Varity’s infrastructure timed out or was interrupted.

This is usually transient. Re-try the deployment:

varitykit app deploy

If it fails repeatedly:

varitykit doctor

This checks connectivity to Varity’s services and reports any reachability issues.

Dynamic Deployment: “Lease acquisition failed”

For dynamic deployments (--hosting dynamic), the compute infrastructure must acquire resources before launching your container. This error means no lease could be established.

Common causes:

Cause	What to check
No available compute capacity	Try deploying again — capacity fluctuates
Container image too large	Optimize your Docker layer or reduce dependencies
Resource request too high	Check your compute config in `varity.config.json`

Recovery:

# Retry the deployment
varitykit app deploy --hosting dynamic

# Check current status
varitykit app status

If the lease consistently fails, fall back to static hosting while you investigate:

varitykit app deploy --hosting static

Dynamic Deployment: “Container failed to start”

The lease was acquired but the container exited immediately after launch.

Common causes:

Missing environment variables — the app crashed on startup because a required env var is absent. Check Environment Variables.
Port mismatch — the container isn’t listening on the expected port. Confirm your app listens on 0.0.0.0, not 127.0.0.1.
Out-of-memory (OOM) — the process was killed by the kernel during startup. Check your package.json for memory-intensive build steps.

Get more detail from logs:

varitykit app info deploy-1737492000

Or via MCP: varity_deploy_logs with limit: 200 for more context.

Dynamic Deployment: “Deployment timed out”

The deployment didn’t become healthy within the expected window.

Typical causes:

Long-running migrations that block app startup
Slow cold-start on first container launch (normal for first deploy — retry once)
App not responding to health check on the expected port

Fix:

Check logs for slow startup output
Move database migrations out of the startup path if possible
Retry — first-launch cold-starts often succeed on the second attempt:
Terminal window
```
varitykit app deploy --hosting dynamic
```

“SDL configuration error” / “Invalid manifest”

The container deployment manifest has a structural problem.

This error is rare and typically means an internal configuration was generated incorrectly. Run:

varitykit doctor

If doctor passes, re-deploy. If the error recurs, report it to support@varity.so with the full output of varitykit app info <deployment-id>.

”App deployed but shows blank page or 404”

The deployment succeeded from Varity’s perspective but the app isn’t serving correctly.

Verify the build output directory exists locally:
- Next.js: .next/ or out/ (for static export)
- React (Vite): dist/
- React (CRA): build/

Confirm the correct output path is used:

npm run build
ls dist/  # or out/, build/, .next/ depending on framework

For Next.js static export, ensure output: 'export' is set in next.config.js
Re-deploy after verifying the output:
Terminal window
```
varitykit app deploy
```

Recovery Path: Rollback

If you can’t diagnose the issue quickly, roll back to the last working version to restore service:

# Find the last working deployment
varitykit app list

# Roll back to it
varitykit app rollback deploy-1737491000

See the full Rollback Guide for details on deployment IDs, caveats with database state, and verifying the restore worked.

Environment Check

Before chasing logs, run a full environment diagnostic:

varitykit doctor

This checks:

Check	What it verifies
CLI installed	`varitykit` is on PATH and up to date
Authentication	You’re logged in with valid credentials
Network	Varity services are reachable
Project structure	`package.json` and build config exist

Getting More Help

If you’re still stuck after reading logs and running diagnostics:

Discord — #support channel — fastest response
GitHub Issues — varity-labs/varity-sdk — attach the output of varitykit app info <deployment-id>
Email — support@varity.so

When reporting an issue, include:

Full output of varitykit app info <deployment-id>
Output of varitykit doctor
Your OS, Node.js version, and Python version

Rollback a Deployment — revert to a previous version
Deploy Your App — full deployment guide
Environment Variables — configure your app’s environment
MCP Server — varity_deploy_logs, varity_deploy_status
Troubleshooting — general CLI and SDK issues