{"record":{"id":"f9862034799addcb","repo":"larksuite/cli","slug":"lark-cli-exited-with-completed-returncode","errorCode":null,"errorMessage":"lark-cli exited with {completed.returncode}","messagePattern":"lark-cli exited with (.+?)","errorType":"exception","errorClass":"LarkCliError","httpStatus":null,"severity":"error","filePath":"skills/lark-sheets/scripts/lark_sheet_read_cli.py","lineNumber":82,"sourceCode":"    for key, value in (flags or {}).items():\n        _append_flag(cmd, key, value)\n\n    try:\n        completed = subprocess.run(\n            cmd,\n            capture_output=True,\n            text=True,\n            timeout=timeout,\n            check=False,\n        )\n    except FileNotFoundError as exc:\n        raise LarkCliError(\"lark-cli not found\", cmd=cmd) from exc\n    except subprocess.TimeoutExpired as exc:\n        raise LarkCliError(f\"lark-cli timed out after {timeout}s\", cmd=cmd) from exc\n\n    if completed.returncode != 0:\n        detail = (completed.stderr or completed.stdout or \"\").strip()\n        raise LarkCliError(detail or f\"lark-cli exited with {completed.returncode}\", cmd=cmd)\n\n    try:\n        envelope = json.loads(completed.stdout)\n    except json.JSONDecodeError as exc:\n        snippet = completed.stdout[:500].replace(\"\\n\", \"\\\\n\")\n        raise LarkCliError(f\"lark-cli stdout was not JSON: {snippet}\", cmd=cmd) from exc\n\n    if isinstance(envelope, dict) and envelope.get(\"ok\") is False:\n        raise LarkCliError(json.dumps(envelope, ensure_ascii=False), cmd=cmd)\n    if not isinstance(envelope, dict):\n        raise LarkCliError(\"lark-cli returned a non-object JSON payload\", cmd=cmd)\n    return envelope\n\n\ndef envelope_data(envelope: dict[str, Any]) -> dict[str, Any]:\n    data = envelope.get(\"data\")\n    return data if isinstance(data, dict) else envelope\n","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/skills/lark-sheets/scripts/lark_sheet_read_cli.py#L64-L100","documentation":"This error is raised by run_sheets() when the underlying `lark-cli sheets ...` subprocess exits with a non-zero return code but produced no stderr or stdout text to explain why. The wrapper normally forwards the CLI's stderr/stdout as the error detail; when both streams are empty it falls back to this generic message carrying the numeric exit code. It is a transport/invocation-level failure between the Python helper and the lark-cli binary, not a Lark API payload error (those arrive as `ok: false` JSON and raise error 32 instead).","triggerScenarios":"Any call to run_sheets() (via check_sheet, main, detect_subtables, inspect_workbook, or profile_table) where subprocess.run() completes with completed.returncode != 0 AND both completed.stderr and completed.stdout are empty or whitespace-only. E.g. lark-cli crashes hard (segfault, panic before printing), is killed by a signal, or a broken/incompatible lark-cli build exits silently.","commonSituations":"A stale or corrupted lark-cli binary on PATH; running inside a sandbox/container where lark-cli cannot initialize and dies without output; a version mismatch where the installed lark-cli does not support a `sheets` subcommand flag and aborts silently; OOM-killed or signal-terminated process leaving no diagnostic output; a wrapper script that swallows stderr.","solutions":["Run the exact command from the error's `cmd` attribute (available on LarkCliError.cmd) manually in a terminal to reproduce and see any output.","Check `lark-cli --version` and upgrade/reinstall lark-cli to a current release so the `sheets` subcommand exists and behaves correctly.","Verify which lark-cli is being executed (`which lark-cli`) — a shadowing script or alias may be failing silently.","Increase visibility by running the helper with the command executed directly (bypassing capture) or checking system logs for crashes (segfault, OOM-kill).","Retry once; transient resource exhaustion (OOM, signal) can cause silent non-zero exits."],"exampleFix":"# before: generic failure with no detail\ndata = run_sheets(\"read\", url=url, sheet_id=sid)\n# after: surface the invoked command and exit code for debugging\nfrom lark_sheet_read_cli import LarkCliError\ntry:\n    data = run_sheets(\"read\", url=url, sheet_id=sid)\nexcept LarkCliError as exc:\n    print(f\"command {' '.join(exc.cmd)} failed: {exc}\")\n    raise","handlingStrategy":"try-catch","validationCode":"import shutil\nif shutil.which(\"lark-cli\") is None:\n    raise RuntimeError(\"lark-cli not installed or not on PATH\")","typeGuard":"def has_diagnostic(exc: LarkCliError) -> bool:\n    msg = str(exc)\n    return not msg.startswith(\"lark-cli exited with \")  # generic message means no detail was captured","tryCatchPattern":"from lark_sheet_read_cli import LarkCliError\ntry:\n    envelope = run_sheets(\"read\", url=url, sheet_id=sid)\nexcept LarkCliError as exc:\n    if str(exc).startswith(\"lark-cli exited with \"):\n        # no stderr/stdout captured: retry manually with the recorded command\n        print(\"silent failure, cmd:\", exc.cmd)\n    raise","preventionTips":["Keep lark-cli upgraded and verify `lark-cli --version` in your environment setup.","Smoke-test the exact subcommand manually before running automated scripts.","Log LarkCliError.cmd so silent failures can be reproduced.","Run automations in a clean environment without stdout/stderr-mangling wrappers."],"tags":["subprocess","cli","exit-code","python"],"backgroundTag":"subprocess-nonzero-exit","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}