Troubleshooting

Deploy / API errors

400 validation

A field didn’t pass validation. The response lists the offending fields:

{ "error":"validation", "details": { "fieldErrors": { "name": ["name must be dns-safe (a-z, 0-9, -)"] } } }

• name: lowercase letters, numbers, dashes only.
• domain: must be a valid hostname (no spaces, backticks, or special chars).
• dockerfile / context: relative paths only — no leading /, no ...
• Blank optional fields are fine (empty = omitted).
• “one of image, repo or services is required”: you sent none of them.
• “exactly one service must have public: true”: multi-service apps need exactly one public service.

403 quota_exceeded

Your org hit its max_apps limit. Delete an unused app, or ask the admin to raise the cap. Redeploying an existing app is always allowed.

400 unknown_secret

You referenced a secret name in envFrom / secretFiles that doesn’t exist for this app. The response lists missing. Create it first (see Secrets), mind shared vs app scope.

503 sealed

The platform’s master key isn’t loaded (memory-only mode after a reboot). /deploy and /secrets are blocked until an operator runs POST /admin/unseal. On the default auto-unseal setup you won’t see this.

401 missing_bearer_token / invalid_or_expired_token

• Missing/malformed Authorization: Bearer <token> header.
• Access tokens expire (~15 min). Get a new one via /auth/refresh with your refresh token, or just log in again.

429 rate_limited

Too many /auth requests from your IP (limit 30 / 5 min). Wait and retry.

The app deployed but the site doesn’t load

Cert / HTTPS not working on a custom domain

Let’s Encrypt issues the cert on first request via HTTP-01 — DNS must point at the server before that. Check:

dig +short <your-domain>     # must return the server's IP

Fix DNS, then retry. For <name>.<ROOT_DOMAIN> subdomains this is already handled by the wildcard DNS.

App status is failed

Look at the error and logs:

curl -s $API/apps/<appId> -H "authorization: Bearer $TOKEN"   # see last_error + deployments[].error
curl -s "$API/apps/<appId>/logs?tail=500" -H "authorization: Bearer $TOKEN"

Common causes:

• Build failed (repo apps): Dockerfile error, wrong dockerfile/context path, or a private repo without a valid repoToken.
• Wrong port: the platform routes to the port your container listens on. If your app listens on 3000 but you set port: 80, requests 502. Set port correctly and redeploy.
• Image pull failed: typo in the image name/tag, or a private registry (only public images are pulled).

502 / 504 from the domain

The container isn’t listening on the configured port, crashed on startup, or is still booting. Check logs; verify the port.

Push-to-deploy isn’t firing

• Webhook Content type must be application/json.
• The Secret in GitHub must match the one from the deploy response / GET /apps/:id.
• Only pushes to the app’s configured branch trigger a deploy; others are ignored.
• In GitHub → Webhooks → Recent Deliveries you can see the response (a 401 means the secret doesn’t match).

Still stuck?

Grab the app id and recent logs/deployments (commands above) and share them with the platform admin.