Errors & exit codes

Exit codes

The boatramp CLI uses the two standard shell exit codes:

Code	Meaning
`0`	Success.
`1`	Any error.

On failure the CLI prints the error and its cause chain to stderr, then exits 1:

error: failed to publish site "blog"
  caused by: server returned 403 Forbidden
  caused by: token lacks required right site:blog · deploy

The top line is the command-level error; each caused by: is one link deeper in the underlying cause, so the root cause is the last line. Scripts should branch on the exit code (0 vs non-zero) rather than parse the message text.

(The one place a different code appears is the internal container/VMM sandbox worker, which propagates the guest’s exit status — not a surface a user invokes.)

API status codes

When the CLI talks to a server, an HTTP error is surfaced in the cause chain above. The control-plane API uses conventional statuses:

Status	Meaning	Common cause
`400`	Bad request	Malformed body, or an invalid authz policy.
`401`	Unauthenticated	Missing, malformed, expired, or revoked token.
`403`	Forbidden	Valid token without the required right.
`404`	Not found	Unknown site, deployment, or alias.
`409`	Conflict	State precondition failed (e.g. activating a nonexistent deployment).
`413`	Payload too large	Upload exceeds `BOATRAMP_MAX_UPLOAD_BYTES`.
`429`	Too many requests	Rate limit or upload-concurrency cap reached.
`503`	Unavailable	Upload slots exhausted, or the node is not ready.

A non-2xx response carries a JSON { "error": "..." } body, which becomes the deepest caused by: line.

Validation errors

boatramp validate (and sync, which validates first) reports config problems against project.cfg before anything is published — a bad route pattern, an unknown handler import, an unparsable cron schedule, or a credential-shaped value in a handler env. These fail at deploy time, not request time:

error: project.cfg: handler /api env var "TOKEN" looks like a secret; move it to
  [handlers].secrets as a reference to a host env var

See the routing schema for the fields these checks cover.

Store migration

boatramp serve refuses to start on a control-plane store still on the pre-0.2.0 layout, rather than silently reading it under the project-scoped keys. Migrate the store explicitly with boatramp migrate (or start serve --auto-migrate):

error: the control-plane store is not migrated to the project-scoped (0.2.0)
  layout; run `boatramp migrate` first, or start `serve --auto-migrate`

See Migrate to projects.

Resource-name validation

A project, site, function, compute, or workflow name is rejected at the write boundary (CLI or API) if it contains a path separator (/ or \), a *, whitespace, or an ASCII control character, or if it is . or ... This keeps a name from escaping its key prefix or aliasing an authz wildcard, so the create or update fails before anything is written.