Debugging Failed Deployments

Varity Team Core Contributors Updated June 2026

When a deployment fails, the fastest path to recovery is: get the logs → identify the error → fix and redeploy. 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

Re-run the deploy to stream its full output, or preview what would deploy first with --dry-run:

varitykit app deploy
varitykit app deploy --dry-run   # preview without deploying

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: “Could not acquire compute”

For dynamic deployments (--hosting dynamic), Varity must reserve compute before launching your container. This error means no compute could be reserved.

Common causes:

Cause	What to check
No available compute capacity	Try deploying again (capacity fluctuates)
Container image too large	Reduce your image size or trim dependencies

Recovery:

# Retry the deployment
varitykit app deploy --hosting dynamic

# Check current status
varitykit app status

If it consistently fails, fall back to static hosting while you investigate (for apps that can run as static):

varitykit app deploy --hosting static

Dynamic Deployment: “Container failed to start”

Compute was reserved 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 operating system 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
```

“Deployment configuration error”

The container deployment configuration 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: Redeploy a Known-Good Version

If you can’t diagnose the issue quickly, restore service by redeploying a version you know works under the same app name:

# Return to the last working version of your code
git checkout <known-good-commit>

# Rebuild and redeploy under the same name
npm run build
varitykit app deploy --name my-app

See the full Recover a Previous Version guide for the step-by-step flow and caveats with environment variables and database state.

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: varity-labs. Include 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

Recover a Previous Version: redeploy a known-good 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