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 and a message explains what happened. Watch the state under Deployments on the project page. If your AI is connected through MCP or the API, it can poll the build with get_build.

Build failures

• “Another build is already in progress” (409): Only one build runs per project at a time. Wait until the current build reaches ready or error, then start the new one. Nothing is queued automatically, so retry after it finishes.
• “The credentials expired” (410): the guide you copy from your project page carries a deployment key that lasts up to 24 hours, so a guide you saved earlier stops working. Open your project, press Copy again, and paste the fresh guide into your AI, which is all it needs. This only affects deploying: once a deploy succeeds, your running app gets its own permanent key automatically.
• Build ends in error: Read the build error first. It usually explains exactly what failed. Common causes are a zip without package.json, which JustDeploy uses to detect the runtime, or a zip that includes node_modules/ or build output. Include package.json and the lock file, but exclude node_modules/, .next/, and .git/.
• Deploy succeeded, then rolled back: JustDeploy health-checks Web and API projects immediately after deployment. The app must return a normal non-5xx response for GET / without requiring sign-in or a database, listen on the platform port PORT=8080, and not bind to localhost or 127.0.0.1. If the health check fails or the process crashes, JustDeploy automatically restores the previous version. Scheduler projects are not health-checked. See Scheduler issues below.

App is live but not working

• Check the deploy for a warning first: Open the project and go to Deployments. A deployment can reach Ready and still fail to serve a working page because the health check accepts any response. In that case, the deployment shows an amber Deployed, but it may not be working yet note with what the check found, such as every path returning 404. This usually means no route is registered or the app rejects its current host. The note also reports build-time problems, such as an incomplete, deleted, expired, or wrong-project JustDeploy key. The deployment itself may succeed while the app cannot reach its database or files. Your AI receives the same information in the build’s warning field.
• 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, which is useful for tracing one crash.
• A setting or API key is missing: Manage environment variables under Project → Advanced → Environment variables. Saving a value does not update the running app because values are copied during the build. Under Deployments, select Rebuild on the version currently serving, or ask your AI to rebuild the project. This applies to every variable, including values used by web pages.
• 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).
• Logins don’t stick, or a visitor sees someone else’s page: this happens when an app marks personalized pages as cacheable: the shared cache then serves one visitor’s copy to everyone. Any page whose content depends on who is looking at it must be sent with Cache-Control: private. Ask your AI to check what the app sends on those pages. JustDeploy also guards the worst case on its own: a response that sets a cookie is marked private automatically, so a login response is never shared. Apps deployed before this guard pick it up on their next build.
• Real-time features don’t connect: WebSockets aren’t supported. Requests arrive one at a time as request and response, so a connection can’t be held open. On a Web project the attempt is refused outright; on an API project it looks like it connected and then no messages ever arrive, which is the confusing case. Libraries like socket.io fall back to repeated HTTP polling and often keep working, but that isn’t dependable either, because a follow-up poll can reach a different instance and the session gets rejected. For chat, live updates or presence, use a dedicated real-time service and keep this app stateless.
• Put back the version that worked: Open the project and go to Deployments. Find an earlier version that worked and select Redeploy; your AI can do this too. JustDeploy rebuilds that source, so it takes a few minutes, and the current version keeps serving until the replacement is ready. Environment variables keep their current values rather than returning to the older settings. Redeploy is available only for the ten most recent successful deployments.

Scheduler issues

A Scheduler project that “doesn’t run” is usually paused, so 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.

Unlike Web and API projects, a Scheduler deploy is not health-checked and is never rolled back automatically, because there is no inbound request to test and invoking your code to check it would run the job for real. That means a broken update stays live until you replace it. After deploying a Scheduler project, press Run now and read Logs to confirm the new version works.

A Scheduler deployment can still show a warning even though it is not health-checked. During the build, JustDeploy reads the code and flags problems that would break the job, such as an invalid JustDeploy key or an attempt to write outside /tmp. A running app can write only inside that directory. After each deployment, check the amber note under Deployments. Your AI receives the same note in the build’s warning field.

MCP connection issues

Ask your AI to run list_organizations to check the connection. If it returns your organizations, the connection works. If the sign-in page keeps reopening or the client does not list the tools, see MCP for tool-specific remote MCP setup and why “Authorization successful” does not always mean the client is connected.

Custom domain stuck

A domain can stay pending because its DNS records do not match what JustDeploy shows, or because the organization no longer has a paid plan. Check the message on the Custom Domain card first. If it asks for a paid plan, an owner or admin needs to choose one. Otherwise, re-copy the DNS names and values exactly. 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?