Troubleshooting

When a deploy fails or your live app misbehaves, work through this page. It’s written for you and your coding AI — if your AI is doing the deploying, give it this page’s URL and it can diagnose most problems on its own.

Build states

Every deploy is a build that moves through these states:

If something goes wrong the state becomes error with a message explaining what happened. Watch the state on your project page under Deployments — or, if your AI is connected over MCP or the API, it can poll the build itself (get_build).

Build failures

• “Another build is already in progress” (409) — only one build runs per project at a time. Wait for the in-progress build to reach ready or error, then start the new one. Nothing is queued automatically — just retry.
• Build ends in error — read the error message on the build first; it usually says exactly what failed. Common causes: the uploaded zip is missing package.json (JustDeploy detects your runtime from it), or the zip includes node_modules/ or build output it shouldn’t. Zip your source with package.json and the lock file included, and node_modules/, .next/, .git/ excluded.
• Deploy succeeded, then rolled back — JustDeploy health-checks your app right after deploying. Your app must respond with a normal (non-5xx) page on GET / without requiring sign-in or a database, listen on the port the platform sets (PORT=8080), and bind 0.0.0.0 — not localhost. If the health check fails or the process crashes, the deploy is rolled back to the previous version automatically.

App is live but not working

• Read the logs first — open your project → Advanced → Logs (pick a time range, filter for errors). Your AI can fetch the same logs with the get_logs MCP tool or the Logs API. Log lines with the same instance value came from the same running container — useful for tracing one crash.
• A setting or API key is missing — environment variables live in your project → Advanced → Environment variables (or the API). One catch for web apps: variables that start with NEXT_PUBLIC_ are baked in while building — set them before you deploy, then deploy again.
• Some visitors are blocked — if firewall rules exist on the project, any request from a non-matching IP is rejected. Blocked attempts appear in your logs — filter for [JUSTDEPLOY_FIREWALL]. Rule changes take 1–2 minutes to apply. Deleting every rule blocks all traffic (add a rule for 0.0.0.0/0 to allow everyone).

Scheduler issues

A Scheduler project that “doesn’t run” is usually paused — check that its schedule is Active on the project page. Use Run now to trigger a run immediately and confirm the code works; runs are asynchronous, so the result shows up in Logs, not in the response.

MCP connection issues

If the sign-in page keeps reopening, your client failed to store its token — set the server up with your tool’s native remote MCP method (see the setup snippets on the MCP page). “Authorization successful” in the browser only means sign-in finished; the real check is whether list_organizations returns your organizations.

Custom domain stuck

A domain stuck in pending almost always means the DNS records at your provider don’t match what JustDeploy shows — re-copy them exactly (names and values). DNS changes can take up to 24–48 hours to propagate depending on the provider. Domains are managed in the console only; your AI can’t connect one for you.

Still stuck?