Troubleshooting

Build failed

1. Open the failed deployment → Build logs.
2. Confirm Root directory, lockfile (npm/pnpm/yarn), and Node major (18/20/22).
3. Reproduce locally with the same build command.
4. Ensure private npm packages have auth in Variables/secrets.
5. For monorepos, confirm build mode (isolated vs workspace) — see below.

Wrong build mode

Docs: Monorepos — build modes.

Quota blocked on bulk import

• Free plan: max 3 services and max 3 rows per bulk import.
• Selecting more than remaining quota returns 402 and creates zero services.
• Deselect rows or upgrade.

Deployment environments

Duplicate blocked (402 / Free plan)

• Free plans are production only — a second persistent environment returns 402 quota_exceeded.
• Starter ≤ 3, Pro ≤ 10 persistent environments per project.
• Duplicated services/databases also count toward service and DB caps.
• Docs: Environments · Pricing.

Promote missing counterpart / partial

• Promote pairs services by logical key. If Staging has api but Production does not, the confirm modal lists missing rows.
• Opt in to create missing services (quota-checked) or create them manually, then retry.
• Partial success shows per-service deploy links with retry on failed rows.
• Docs: Environments — Promote.

Cannot reach another environment (isolation)

• Services in different environments share a project namespace but are isolated by NetworkPolicy.
• ${{service.api.URL}} resolves inside the current environment only — it will not point at Staging from Production.
• Docs: Variables — references.

Push went to the wrong environment / no deploy

• Git push deploys only services whose branch matches and auto-deploy is on in that environment.
• Unmatched branches do nothing — check Pipeline columns and service Settings (branch / auto-deploy).
• Prefer auto-deploy off on production when you soak via Promote.
• Docs: Deploy — git vs Promote.

Feature disabled (503)

• Duplicate / Promote return 503 feature_disabled when deployment_environments (and dogfood allowlist) are off.
• Existing staging keeps serving; list/switch still work for read paths.

Unsupported Redis / Compose infra

Setup and presets: Managed Redis.

Bytstack does not run Compose. Known Postgres and Redis images (redis, valkey, bitnami/redis, redis-stack-server) become managed offers you can accept in the import checklist; MySQL, Mongo, KeyDB, Kafka, NATS, and similar images appear as unsupported offers and no service is created. Compose secrets are never imported.

Redis offer didn’t appear? Managed Redis must be enabled for your workspace — accepting a Redis offer while it is off fails the import with 503 feature_disabled. Redis instances also count against your plan’s Redis limit: if the selection exceeds it, the whole import is blocked with 402 and nothing is created.

Redis env var missing right after import? The connection URL is injected when the instance becomes ready, not at import time. Watch the instance until it is available, then redeploy if your service needs the variable at build time.

Redis Stack modules: redis-stack-server is offered as managed Redis (Valkey) without modules — RediSearch, JSON, TimeSeries, and Bloom are unavailable. Keep workloads that need them on an external provider.

BYO: For unsupported images, point your app at an external MySQL/Mongo/Kafka/etc. with a service or env-group variable. See Monorepos — Compose and Variables.

Unresolved env references

Deploy fails with env_reference_unresolved, env_reference_cycle, or env_reference_syntax when ${{…}} cannot resolve in the same project and environment. Check service/group/database names and avoid cycles. Docs: Variables — references.

Deploy stuck or never live

• Watch for readiness / health-check failures — web services may wait until probes succeed.
• Confirm the start command binds 0.0.0.0 and uses PORT.
• Check runtime logs for crash loops (bytstack logs or Service → Logs).
• Service → Metrics shows restart count, CPU, and memory. Workspace Settings → Alerts can page on restart loops or health failures.

Domain not verifying / no HTTPS

• DNS must match the dashboard records (TXT challenge + CNAME/ALIAS). Propagation can take minutes to hours.
• Apex domains often need ALIAS/ANAME or provider flattening — plain CNAMEs may not work at the zone apex.
• After DNS is correct, wait for certificate issuance; re-check the domain status panel.
• Stage bindings: confirm the host is attached to the intended environment.

GitHub import empty or unauthorized

• Reinstall/update the GitHub App with access to the target org/repos.
• Login OAuth alone is not enough — the App grants repository access.
• For monorepo analyze returning empty candidates, confirm the App can read the default branch and the tree is not truncated.

Database connection refused

• Prefer the internal URL from services in the same environment.
• If using external access, confirm IP allowlist and TLS settings.
• After credential rotation, update Variables and redeploy consumers.

CLI auth errors

• Run bytstack login (or set BYTSTACK_TOKEN).
• Confirm BYTSTACK_API_URL / linked .bytstack/config.json apiUrl points at the right API.
• Ensure the directory is linked: bytstack link <serviceId> or bytstack link --project <projectId> for deploy --all / env groups.
• For multi-env: bytstack environment select staging (or --environment) before project-scoped env / deploy --all.

Still stuck?

Gather: service ID, deployment ID, environment slug, approximate time (UTC), and a redacted log snippet. Platform operators can correlate control-plane and cluster events from those identifiers.