Troubleshooting builds and deployments

First read the failed deployment's error on the project's Deployments tab (full text on the AI Debug tab). If the build passed but the app failed, read the Logs tab. Scan deployments on AI Debug diagnoses most of these automatically.

"no git source or image configured"

Symptom: A new project's first deployment failed instantly.

Cause: Projects deploy once on creation, before a source is set.

Fix:

1. Set a repository (Provider), image (Deploy from Image) or compose file, then Save.
2. Click Deploy.

git clone failed

Symptom: "git clone failed" with "Repository not found", "Authentication failed" or "Remote branch … not found".

Cause: Private repo without access, wrong URL, or missing branch.

Fix:

1. GitHub: connect or reconnect in Settings → GitHub with an account that can see the repo.
2. Other hosts: add a token in Settings → Git credentials and use an https:// URL, not git@….
3. Check the Branch exists, Save, deploy.

Nixpacks can't detect the app

Symptom: "nixpacks build failed" saying no build plan or provider was found.

Cause: No language files (package.json, requirements.txt, go.mod…) at the repository root, or an unsupported language.

Fix:

1. Move the app to the root, or use the monorepo options in Dockerfiles, images and Compose.
2. Or add a root Dockerfile and choose Dockerfile.

No start command

Symptom: Nixpacks reports no start command, or the container exits immediately.

Cause: Nixpacks couldn't infer how to start the app.

Fix:

1. Add a start script, a Procfile (web: <command>) or [start] cmd in nixpacks.toml.
2. Commit, push, deploy.

Lockfile out of sync

Symptom: "npm ci can only install packages when your package.json and package-lock.json … are in sync", "yarn was run with --frozen-lockfile", or ERR_PNPM_OUTDATED_LOCKFILE.

Cause: Installs follow the lockfile exactly and it doesn't match package.json.

Fix:

1. Run npm install / yarn install / pnpm install locally and commit the lockfile.
2. Keep only one lockfile.

Wrong runtime version

Symptom: Syntax errors or "unsupported engine" while building.

Cause: The repo doesn't pin a version, so Nixpacks used its default.

Fix:

1. Pin it: engines.node or .nvmrc, .python-version, go.mod, .ruby-version.
2. NIXPACKS_* variables on the Environment tab have no effect (variables don't reach the build); use nixpacks.toml.

Private dependencies

Symptom: 401/404 from a private package registry, private Git dependencies failing, or missing submodule files.

Cause: Builds get no project variables or secrets, and submodules aren't cloned.

Fix:

1. Build the image in CI, push it to a registry, add the registry in Settings → Registries.
2. Deploy it with Deploy from Image. Or vendor the dependency.

Dockerfile not found

Symptom: "build_type is dockerfile but no Dockerfile found in repo".

Cause: MarvX only uses a file named exactly Dockerfile at the repository root.

Fix:

1. Move or rename it to /Dockerfile.
2. Or switch Build Type to Nixpacks.

docker, nixpacks or buildpacks build failed

Symptom: "docker build failed" (or nixpacks/buildpacks) followed by build output.

Cause: One of your build steps failed, or a builder is unavailable.

Fix:

1. Read the last lines; they're your build's output (failing RUN, missing COPY file, compile error).
2. Reproduce locally with docker build . or nixpacks build . from the repo root.
3. "the pack CLI is not installed" means Cloud Native Buildpacks aren't available: use Nixpacks or Dockerfile.

Build timed out

Symptom: The build stops after about 15 minutes (20 for Buildpacks, 10 for static), or the clone after 5.

Cause: The build exceeds the time limit.

Fix:

1. Speed it up: fewer dependencies, multi-stage Dockerfile, no tests during deploy.
2. Or build in CI and use Deploy from Image.

Out of memory (exit code 137)

Symptom: The app keeps restarting, logs stop abruptly, or the deploy fails right after starting; Monitoring shows memory near the cap.

Cause: The app exceeded its plan's per-app cap (Free 512 MB, Starter 1 GB, Pro 2 GB, Enterprise 8 GB) and was killed.

Fix:

1. Use less memory: fewer workers, smaller caches, NODE_OPTIONS=--max-old-space-size=384 or JAVA_TOOL_OPTIONS=-Xmx384m (adjust to your cap).
2. Don't build at startup (no npm run build in start).
3. Upgrade for a higher cap.

"build/deploy failed" after a good build, or 502 Bad Gateway

Symptom: The build passed but the deploy failed, or the deploy succeeded and visitors get 502.

Cause: The container crashed within seconds, or it isn't listening on PORT.

Fix:

1. Read the Logs tab for the crash (missing variable, database connection, code error).
2. Listen on 0.0.0.0 and PORT (default 3000), not localhost or a hard-coded port.
3. For images with a fixed port, set PORT to it. Deploy again.

Environment variable missing at runtime

Symptom: A variable you added is undefined.

Cause: Not saved, not redeployed, or needed at build time.

Fix:

1. Check the Environment tab and click Save.
2. Click Deploy (Reload keeps old variables).
3. For build-time values (NEXT_PUBLIC_*, VITE_*) see Environment variables.

Could not pull image

Symptom: "could not pull image" or "registry login failed".

Cause: Wrong image or tag, missing credentials, or a temporary registry problem.

Fix:

1. Check the reference and tag.
2. Add credentials in Settings → Registries; the image must start with the saved host (Docker Hub: docker.io/owner/image:tag).
3. "The registry didn't respond in time": retry shortly.

Compose deployment failed

Symptom: "compose up failed".

Cause: Invalid file, a build: path (the repo isn't cloned for Compose), or an image that can't be pulled.

Fix:

1. Validate locally with docker compose config.
2. Use image: for every service.
3. If the error isn't from your file, contact support.

Deployment stuck

Symptom: queued or deploying for much longer than usual.

Cause: A busy queue, a slow build, or a platform problem.

Fix:

1. Allow up to the build timeouts above.
2. Then Cancel and deploy again.
3. Contact support if it repeats.

Deploy refused (402)

Symptom: A plan-limit dialog or one of these messages.

Cause: A limit was reached, a payment is overdue, or the workspace is suspended.

Fix: