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 env/secrets.

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).

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.

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.

Database connection refused

• Prefer the internal URL from services in the same project.
• If using external access, confirm IP allowlist and TLS settings.
• After credential rotation, update env 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>.

Still stuck?

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