Docs
DeployxaDocs Portal
CLI v1.0.4
Troubleshooting Guide
Support

Troubleshooting

A short path from “it failed” to the cause. Start with the log, then match the symptom below.

First three commands

shell
$ deployxa doctor                 # local tools, token, API reachability, link
$ deployxa status                 # latest deployment status and URL
$ deployxa logs <deploymentId>    # the full build and runtime log

A failed deployxa deploy prints the deployment ID to pass to deployxa logs. In the dashboard, open the deployment from Deployments to see its timeline and log together. deployxa ai diagnose and AI Copilot can suggest a fix.

Build failures

Symptom in the logLikely causeFix
git clone failed / repository not foundWrong URL, missing branch, or no access to a private repoCheck the URL and branch; reconnect GitHub or use a token with repo access.
branch … not foundThe configured branch does not existFix the branch in the project settings.
framework detection failedDeployxa could not tell what to buildSelect the framework manually and set the build command, or add a Dockerfile.
docker build failed / build failedAn error in your build script or DockerfileRun the build locally (deployxa build or docker build) and fix the first error in the log.
out of memory / OOMThe build or app exceeded the plan’s memoryReduce memory use (e.g. NODE_OPTIONS=--max-old-space-size) or upgrade.
timeout / timed outA step took too longUse the build cache (Pro+), trim dependencies, avoid downloads during build.
permission denied / unauthorizedGit access was refusedRe-authorize GitHub for the repository.
PROJECT_NAME_TAKENA project with that name already existsOpen the existing project or pick another name.

Deployed, but the site does not work

502, 503 or the app never becomes healthy

  • The server listens on localhost. Bind to 0.0.0.0.
  • The app listens on a different port from the one configured. Check deployxa inspect and read PORT in your code.
  • The start command exits. A web server must keep running in the foreground.
  • A required environment variable is missing, so the app crashes at boot. Check deployxa logs --live while it starts.

Works locally, fails in production

  • Missing variables: compare deployxa env list with your local .env.
  • Build-time variables (NEXT_PUBLIC_*, VITE_*) changed without a rebuild: run deployxa redeploy.
  • Case-sensitive file paths: Linux treats Logo.png and logo.png as different files.
  • Dev-only dependencies needed at runtime: move them to dependencies.

Single-page app returns 404 on refresh

Client-side routes need a fallback to index.html. See the React guide.

First request is slow

Free apps idle after 20 minutes without traffic; the first request wakes them.

Domains and HTTPS

  • Stuck on Waiting: the A/CNAME record is missing or wrong, or still propagating. Compare with dig +short <domain> and the values on Dashboard → Domains, then retry verification.
  • Behind a proxy or CDN: add the _deployxa-challenge TXT record so ownership can be verified.
  • Was working, now flagged: the domain stopped resolving to Deployxa, often after a DNS provider change. Fix the record and retry.

CLI problems

MessageFix
Project must be linked … Run "deployxa link" firstRun deployxa link or deployxa init in the app folder, or pass a project ID where supported.
Session expired or authentication faileddeployxa login. In CI, check DEPLOYXA_TOKEN includes the "Bearer " prefix, or use deployxa login --token.
Cloud control plane connection failedCheck internet access and DEPLOYXA_API_URL / deployxa config; deployxa doctor shows API reachability.
Rate limit exceededWait and retry; slow down scripted loops.
Failed to package foldertar is missing or a file is unreadable; check permissions with deployxa doctor.
Only .zip and .tar.gz/.tgz files are supportedPass a folder or one of those archive types to deployxa deploy.
A new project appeared after a CI deployThe runner had no .deployxa/config.json. Use deployxa deploy <projectId> . in CI.
Login page does not openOpen http://localhost:5678/login manually; make sure port 5678 is free.

Roll back first, debug second

If production is broken, restore the last good release, then investigate:

shell
$ deployxa rollback previous

Still stuck?

Check platform status, then open a ticket from Dashboard → Support or email support@deployxa.com. Include the deployment ID, the first error in the log, and the output of deployxa doctor. Support level depends on your plan (Community, Email, Priority or Dedicated).