Skip to content

Troubleshooting

Errors

Failures print to stderr and never to stdout, so a script or agent parsing stdout never sees a half-result. The shape follows --format:

  • table / tsv (default): Error: <message>
  • json / toon: a structured {"error": "<message>"} object (toon-encoded under toon)
1
waldur-cli team customer list --format json 2>err.json   # stdout is the result, stderr the error

Because structured formats emit structured errors, an agent consuming --format json can handle success and failure through one JSON parser without a separate error path.

A batch (delete, or a bodyless action, over several UUIDs) is the one place per-item errors go to stderr as they happen rather than at the end: error: <uuid>: <message>, one line per failed item, interleaved with the successful items' normal stdout output. The command still exits non-zero if anything failed, with a final <N> of the batch failed: <uuids> summary.

Exit codes

  • 0 — success
  • non-zero — failure (a client-side validation error, an API error, a failed/timed-out order, …). Combined with clean stdout, this makes the CLI safe in set -e scripts and pipelines: waldur-cli ... > out.json || handle_error.

Common messages

Message Cause Fix
unknown filter key ... --filter key isn't a real filter for this resource check the listed valid keys, or the resource's --help
invalid --filter ...expected true or false (or an integer) a --filter value doesn't match the field's type pass a value of the right type
the request body is not valid JSON for this resource's request schema malformed JSON, or a field with the wrong type, in --request --generate-skeleton to see the expected shape
... This field may not be null an explicit null sent for a non-nullable optional field omit the field (a --generate-skeleton template already does)
marketplace order ... erred: <message> the async order failed server-side read the surfaced error_message; check the order in the Waldur UI
timed out after Ns waiting for marketplace order ... the order didn't reach a terminal state in time it may still complete — check later, or retry with a larger --timeout
API error 401 missing/invalid/expired token re-check --token/WALDUR_ACCESS_TOKEN, or login again
... request failed after a pause the request timed out, or exhausted its retries raise --http-timeout/--max-retries; see below

Timeouts and retries

Every request has a 60-second cap and transient failures are retried automatically — a connection error, a request timeout, a 5xx, or a 429 rate limit, up to 3 times with exponential backoff. Both are tunable, globally or per command:

1
2
3
waldur-cli team customer list --http-timeout 15 --max-retries 5
export WALDUR_HTTP_TIMEOUT=15 WALDUR_MAX_RETRIES=5   # or via the environment
waldur-cli team customer list --max-retries 0        # 0 disables retrying

Two things worth knowing:

  • Only replayable requests are retried. list/get/delete are; create, update, and provision are not. A POST that times out may still have been applied server-side, so replaying it could duplicate the effect — for provision that means a second marketplace order to pay for. Those fail fast instead, and you decide whether to re-run.
  • Client errors are never retried. A 4xx (other than 429) will fail identically every time, so retrying it would only delay the message.

--http-timeout is per HTTP request, and is unrelated to provision/terminate/wait's own --timeout, which bounds a whole poll-until-done operation made of many requests.

Debugging (--debug)

--debug prints one line per HTTP request to stderr — method, URL, status, timing — as each happens, regardless of --format. It's the quickest way to see exactly what a command does (including auto-pagination fetching multiple pages, or an order being polled), and to understand a server-side rejection:

1
2
3
4
waldur-cli team customer list --debug 1>/dev/null
# 2026-07-22T03:03:35Z  INFO HTTP request{http.request.method=GET
#   server.address=waldur.example.com ... http.response.status_code=200}:
#   close time.busy=299µs time.idle=460µs

Since --debug writes to stderr, 1>/dev/null (or > out.json) leaves you with just the trace, and the normal result still goes to stdout.

Shell completions

waldur-cli completions <shell> prints a completion script for bash, zsh, fish, powershell, or elvish, covering the whole subcommand tree and flags:

1
2
3
4
5
6
7
8
# bash
waldur-cli completions bash > ~/.local/share/bash-completion/completions/waldur-cli

# zsh (any directory on your $fpath)
waldur-cli completions zsh > "${fpath[1]}/_waldur-cli"

# fish
waldur-cli completions fish > ~/.config/fish/completions/waldur-cli.fish

Reload your shell (or source the file) and tab-completion works across groups, resources, verbs, and flags.

Getting help

Every command documents itself. When in doubt, append --help — it's generated from the same schema the commands are, so the valid --filter keys, --fields values, and required arguments it shows are always accurate for the version you're running:

1
waldur-cli openstack instance provision --help