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.

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

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