langchain-ai/deepagents · error · SystemExit

--list must be positive

Error message

--list must be positive

What it means

Argument validation in `main()`: when `--list N` is used, N must be >= 1. A non-positive list size is nonsensical (can't list 0 threads), so the CLI exits.

Source

Thrown at libs/code/deepagents_code/built_in_skills/deepagents-thread-inspector/scripts/inspect_sessions.py:608

    )
    return parser


def main() -> None:
    """Parse arguments, inspect the session store, and write JSON to stdout.

    Raises:
        SystemExit: If the command-line arguments are invalid, the local session
            store is missing or unsupported, or the Deep Agents Code runtime
            cannot be located.
    """
    args = _build_parser().parse_args()
    if args.max_content < 1:
        msg = "--max-content must be positive"
        raise SystemExit(msg)
    if args.list_limit is not None and args.list_limit < 1:
        msg = "--list must be positive"
        raise SystemExit(msg)
    if args.list_limit is None and not args.thread_id:
        msg = "Provide a thread ID or use --list N"
        raise SystemExit(msg)
    if args.list_limit is not None and args.thread_id:
        msg = "Use either a thread ID or --list N, not both"
        raise SystemExit(msg)

    _ensure_runtime()
    warnings.filterwarnings(
        "ignore",
        message=(
            "Core Pydantic V1 functionality isn't compatible with Python 3.14 "
            "or greater.*"
        ),
    )
    collected_warnings: list[str] = []
    result: dict[str, object]
    conn = _connect_read_only(args.db)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass a positive integer: `--list 20`
2. Omit the value handling by just using `--list` with its intended count
3. If you want all threads, use a sufficiently large N rather than 0

Example fix

// before
inspect_sessions.py --list 0
// after
inspect_sessions.py --list 20

list_n = parse_list_arg()
if list_n is not None and list_n < 1:
    list_n = 10  # or raise before invoking

def is_valid_list_limit(v: object) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v >= 1)

try:
    run_inspector(list_limit=n)
except SystemExit as e:
    if "--list must be positive" in str(e):
        run_inspector(list_limit=10)
    else:
        raise

When it happens

Trigger: Running `inspect_sessions.py --list 0` or `--list -5`.

Common situations: Scripted usage where a limit variable was unset or computed as 0; misunderstanding `--list` as a boolean toggle and passing 0.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid JSON in --model-params: {json_str!r}. Expected forma
• --model-params must be a JSON object, got {type}
• --max-content must be positive
• dcode: {message}
• Could not resolve {label} path {raw_path!r}: {exc}. Ensure t

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/89885e083debbd8f. Report an issue: GitHub.