Skip to content
Szenera DeveloperDocs
CLI › In scripts › When the CLI aborts
Chapters

When the CLI aborts

Unknown command, profile blocked, 401 despite a key, response contradicts the contract, exit 11 or 12: symptom, meaning, solution.

6 minute readCLIUpdated: 10/25/2026

On this page

Before you start

For
Anyone who has issued a command and sees a message with ✗ or {"error": …} instead of a result
Prerequisite
the exit code of the call (echo $? right after the command), and a call through node …/dist/main.js or szenera, not through pnpm run

The most common aborts of the CLI, in the order in which they occur: with the message you see, the exit code, its meaning, and the way back. Each solution points to the page that covers the topic.

Symptom Meaning Solution
Unbekannter Befehl „device lister". (unknown command) and below it the whole overview (exit 1) The words match no command in the registry: a typo, the wrong order (list device), or a flag without = that was read as a word. Choose the command from the overview. Flags carry their value after the equals sign (--limit=20). See Commands for your organization.
„device list" kennt die Flagge „--state" nicht. Bekannt sind: … (unknown flag) (exit 1) An unknown flag is an error, not a silent hint. The message lists the valid ones. Use one of the flags the message names. szenera <befehl> --help explains them.
„--limit" braucht einen Wert: --limit=<anzahl>. (flag needs a value) (exit 1) The flag was given without an equals sign. --limit 20 does not exist. Write --limit=20.
„device get" braucht <id> — … (positional argument missing) (exit 1) A required positional argument is missing. Append the ID as --help shows it.
„scn_01K…" ist keine Kennung für ein Medium: erwartet wird ast_… (not an ID for a media item) (exit 1) The prefix of the ID does not match the command. No call went out. Use the right ID: ast_ media item, scn_ scene, pll_ playlist, sch_ program, ply_ display, dev_ device.
… wandert in den Papierkorb. Wenn das gewollt ist: --yes anhängen. (moves to the trash, append --yes if intended) (exit 1) An irreversible action without consent in the call. Append --yes if the consequence is intended.
Keine Konfiguration gefunden — die Kommandozeile weiß nicht, mit welcher Umgebung sie sprechen soll. (no configuration found) (exit 2) Neither a file at one of the two locations nor SZENERA_BASE_URL. Create a profile or set SZENERA_BASE_URL and SZENERA_API_KEY. See Profiles and credentials.
Unbekanntes Profil „staging". … führt: dev, prod. (unknown profile) (exit 2) --profile= or SZENERA_PROFILE names a profile the file does not hold. Choose one of the names listed.
„asset delete" ist im Profil „prod" gesperrt — das Profil ist schreibgeschützt. (blocked, the profile is write-protected) (exit 2) A command that changes something meets a write-protected profile, or one without the setting, in which case true applies. If the profile may write: set readOnly: false. See Profiles and credentials.
Kein API-Schlüssel: erwartet wird ein Wert mit dem Präfix 'ak_' oder 'opk_' … (not an API key) (exit 2) The value in the profile or in SZENERA_API_KEY is not a key: truncated, swapped, empty. Take the plaintext from the portal. See Profiles and credentials.
„whoami" braucht einen Ausweis, das Profil „…" trägt keinen. (needs a credential, the profile has none) (exit 1) The profile has credential: {"kind": "none"} or none at all. Only health and health public run that way. Add SZENERA_API_KEY=ak_… or set credential in the profile.
HTTP 401 (exit 3) despite a key that is set The key is not valid: revoked, expired, or the profile points to a different environment than the one the key was issued for. Check each profile with szenera whoami --profile=<name> and create a new key. See Profiles and credentials.
HTTP 403 Permission.Denied (exit 4) The credential is valid but the permission is missing, or the route requires a permission that a key may not carry (such as identity.device.list). Check the “Key” column of the command pages. Extend the key’s permissions or use a profile with password sign-in.
Die Anfrage an „composition.scenes.update" entspricht nicht dem Vertrag: (the request does not match the contract) with field paths (exit 1) Your input, usually a file behind --document or --entries, does not conform to the schema. No network packet went out. Correct the fields named in the file. See JSON output and exit codes.
Die Antwort auf „…" widerspricht dem Vertrag, den diese CLI (0.1.0) kennt. (the response contradicts the contract) (exit 9) Version skew: the other end is older or newer than the CLI, and not broken. Append --raw. The raw response on standard output shows which field is missing. Build the CLI from the matching version. See JSON output and exit codes.
HTTP 409 (exit 6) on scene update, playlist update, role update The expected version no longer matches: someone changed it in between. Call again without --version (the command then reads the version itself). scene update --retry retries once on its own.
HTTP 422 (exit 7) with Scene.PublishValidationFailed The live check of the document failed: a media item is gone, a template was deleted. Fix the cause. Findings cannot be skipped here.
HTTP 429 (exit 8) Too many calls. retryAfterSeconds is in the error. Wait that long, then retry. See Scripts and CI.
Network.RequestFailed, fetch failed (exit 10) No HTTP response at all: wrong address, no network, no name resolution. Check SZENERA_BASE_URL or services in the profile. szenera health needs no credential and separates network from sign-in.
health ends with exit 9 The environment reports that it is not ready: HTTP 503 on GET /health/ready. Wait and check again. The table names the check that is red.
Exit 11 after asset upload, device get-command --wait The operation went through and ended in failure: processing failed, command failed. Read the finding in the error. asset reprocess is the way back for a media item in the state error. See Scripts and CI.
Exit 12 Zeitlimit … erreicht — der Ausgang ist unbekannt. (time limit reached, outcome unknown) The time limit took effect. The operation may still be running. Do not retry blindly. First check with asset get or device get-command, then run again with a larger --timeout. See Scripts and CI.
„abc" ist keine Dauer. Erlaubt sind 500ms, 90s, 20m, 2h — oder eine Zahl in Sekunden. (not a duration) (exit 1) --timeout or --interval uses a format the CLI does not recognize. Use one of the formats named.
„--limit=500" liegt außerhalb von 1…200. (out of range) (exit 1) The contract allows no more per page. Use --limit=200 and --all. See Scripts and CI.
Der Rumpf ist kein gültiges JSON (the body is not valid JSON) on api post (exit 1) The shell changed the body: quotes, dollar signs, line breaks. Pass larger bodies as a file: @rumpf.json.
Every error ends with exit 1, whatever happens The call runs through pnpm run, which swallows the codes. Call node packages/cli/dist/main.js … directly. See JSON output and exit codes.
The output is a table although a script reads it, or JSON in the terminal The format follows standard output: terminal means table, pipe means JSON. SZENERA_OUTPUT can override that. Force --json or --table.
The command ends with exit 0, but ergebnis.json does not contain .daten There is no envelope: standard output carries the payload directly. Read .items[] instead of .daten.items[]. See JSON output and exit codes.