larksuite/cli · error · LarkCliError

lark-cli exited with {completed.returncode}

Error message

lark-cli exited with {completed.returncode}

What it means

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).

Source

Thrown at skills/lark-sheets/scripts/lark_sheet_read_cli.py:82

    for key, value in (flags or {}).items():
        _append_flag(cmd, key, value)

    try:
        completed = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=timeout,
            check=False,
        )
    except FileNotFoundError as exc:
        raise LarkCliError("lark-cli not found", cmd=cmd) from exc
    except subprocess.TimeoutExpired as exc:
        raise LarkCliError(f"lark-cli timed out after {timeout}s", cmd=cmd) from exc

    if completed.returncode != 0:
        detail = (completed.stderr or completed.stdout or "").strip()
        raise LarkCliError(detail or f"lark-cli exited with {completed.returncode}", cmd=cmd)

    try:
        envelope = json.loads(completed.stdout)
    except json.JSONDecodeError as exc:
        snippet = completed.stdout[:500].replace("\n", "\\n")
        raise LarkCliError(f"lark-cli stdout was not JSON: {snippet}", cmd=cmd) from exc

    if isinstance(envelope, dict) and envelope.get("ok") is False:
        raise LarkCliError(json.dumps(envelope, ensure_ascii=False), cmd=cmd)
    if not isinstance(envelope, dict):
        raise LarkCliError("lark-cli returned a non-object JSON payload", cmd=cmd)
    return envelope


def envelope_data(envelope: dict[str, Any]) -> dict[str, Any]:
    data = envelope.get("data")
    return data if isinstance(data, dict) else envelope

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Run the exact command from the error's `cmd` attribute (available on LarkCliError.cmd) manually in a terminal to reproduce and see any output.
2. Check `lark-cli --version` and upgrade/reinstall lark-cli to a current release so the `sheets` subcommand exists and behaves correctly.
3. Verify which lark-cli is being executed (`which lark-cli`) — a shadowing script or alias may be failing silently.
4. Increase visibility by running the helper with the command executed directly (bypassing capture) or checking system logs for crashes (segfault, OOM-kill).
5. Retry once; transient resource exhaustion (OOM, signal) can cause silent non-zero exits.

Example fix

# before: generic failure with no detail
data = run_sheets("read", url=url, sheet_id=sid)
# after: surface the invoked command and exit code for debugging
from lark_sheet_read_cli import LarkCliError
try:
    data = run_sheets("read", url=url, sheet_id=sid)
except LarkCliError as exc:
    print(f"command {' '.join(exc.cmd)} failed: {exc}")
    raise

import shutil
if shutil.which("lark-cli") is None:
    raise RuntimeError("lark-cli not installed or not on PATH")

def has_diagnostic(exc: LarkCliError) -> bool:
    msg = str(exc)
    return not msg.startswith("lark-cli exited with ")  # generic message means no detail was captured

from lark_sheet_read_cli import LarkCliError
try:
    envelope = run_sheets("read", url=url, sheet_id=sid)
except LarkCliError as exc:
    if str(exc).startswith("lark-cli exited with "):
        # no stderr/stdout captured: retry manually with the recorded command
        print("silent failure, cmd:", exc.cmd)
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• --header-scan-rows must be at least 1
• +csv-get truncated the requested range at {source_range}; na
• Pass exactly one of --url or --spreadsheet-token
• Pass only one of --sheet-id or --sheet-name
• lark-cli timed out after {timeout}s

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/f9862034799addcb. Report an issue: GitHub.