Troubleshooting — Guidal Docs

CLI exit codes

The CLI returns a distinct exit code per failure class, so scripts can branch on the reason rather than parsing output. These are a stable contract — numbers are never reused for a different meaning.

Code	Meaning	Typical cause
`0`	Success	—
`1`	Unspecified error	An unexpected failure
`2`	Usage or validation error	A bad flag, a name that already exists, an invalid value
`3`	Authentication or authorization	Not signed in, expired session, or insufficient role
`4`	Not found	The named service, database or project does not exist
`5`	Plan or quota restriction	A limit reached, or a capability not in your plan
`6`	Server or connection failure	A platform error, or the API was unreachable

Branching on them in a deploy script:

bash

guidal services deploy api --image ghcr.io/org/app:"$GIT_SHA"
case $? in
  0) echo "deployed" ;;
  3) echo "auth failed — is GUIDAL_ACCESS_TOKEN set and valid?"; exit 1 ;;
  5) echo "plan limit reached — check guidal billing usage"; exit 1 ;;
  6) echo "platform or network error — safe to retry"; exit 1 ;;
  *) echo "deploy failed"; exit 1 ;;
esac

Code 6 is the one worth retrying automatically. Codes 2 through 5 will fail identically on a retry — they need a change of input, credentials, or plan.

A service will not start

Read its logs first — the reason is almost always there:

bash

guidal logs query --service api
guidal deployments diagnostics --service api

The usual causes, in rough order of frequency:

Port mismatch. --port must match the port the application actually binds. A service listening on 3000 but created with --port 8080 starts fine and never receives traffic.

Missing configuration. An application that reads a required environment variable at startup exits immediately when it is absent. guidal env list --service api shows what is set — remember a newly set variable needs a redeploy.

Binding to localhost. An application bound to 127.0.0.1 accepts connections only from inside its own container. Bind to 0.0.0.0.

Image architecture. An image built only for arm64 on an Apple laptop will not run on amd64 hosts. Build multi-architecture images, or target amd64.

A dependency not ready. A service that crashes because the database is still provisioning will keep restarting until it is available. Check the database reached a running state.

A deploy succeeded but the old version is serving

Deploys roll out gradually and the previous version keeps serving until the new one is healthy. If the new version never becomes healthy, the old one continues indefinitely — which is the intended protection, but looks like a deploy that did nothing.

bash

guidal deployments list --service api

Check the newest deployment's status. If it is not healthy, its logs will say why.

Configuration changes seem ignored

Environment variables and secrets are read when the container starts. Setting one does not affect the running process:

bash

guidal services deploy api

Authentication failures

bash

guidal auth status
guidal login

In CI, confirm GUIDAL_ACCESS_TOKEN is exported and the key has not been revoked. Exit code 3 with a valid-looking key usually means the key was deleted or the account's role changed.

Hitting a limit

Exit code 5 names the limit. To see where you stand:

bash

guidal billing usage

Either free capacity — delete unused services, remove old registry tags — or change plan. See Plans, billing and limits.

A domain will not verify

DNS propagation takes time; a verification that fails moments after you add the record is usually just early. Confirm the record resolves:

bash

dig +short app.example.com

The answer must match what guidal domains add printed. If your DNS provider proxies traffic by default, disable that until verification completes.

Logs look incomplete

Each plan has a per-second line rate. Output beyond it is sampled rather than dropped wholesale — so a service logging in a tight loop will show gaps. Reduce log volume rather than assuming lines are being lost. See Logs.

Getting more detail

bash

guidal <command> --help
guidal deployments diagnostics --service api
guidal network topology

If a problem persists and looks like a platform fault rather than a configuration one, reach us through the contact page with the service name, the approximate time, and the exit code you saw.