langchain-ai/deepagents · error · SystemExit

Provide a thread ID or use --list N

Error message

Provide a thread ID or use --list N

What it means

`main()` requires exactly one mode of operation: either a thread ID to inspect or `--list N` to enumerate threads. With neither provided, the script cannot proceed and exits with this usage error.

Source

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

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)
    try:
        if args.list_limit is not None:
            if args.include_metadata or args.mode != "latest-turn":

View on GitHub (pinned to a1af029e6e)

Solutions

1. Provide a thread ID: `inspect_sessions.py <thread-id>`
2. Or list available threads first: `inspect_sessions.py --list 10`
3. Run with `--help` to review the required arguments

Example fix

// before
inspect_sessions.py            # no thread, no --list
// after
inspect_sessions.py --list 10  # discover, then inspect a thread

args = sys.argv[1:]
has_thread = bool(args) and not args[0].startswith("--")
has_list = "--list" in args
if not has_thread and not has_list:
    raise ValueError("provide a thread ID or --list N")

def has_inspection_target(argv: list[str]) -> bool:
    has_thread = bool(argv) and not argv[0].startswith("--")
    has_list = any(a == "--list" for a in argv)
    return has_thread != has_list

try:
    run_inspector(*argv)
except SystemExit as e:
    if "Provide a thread ID" in str(e):
        run_inspector("--list", "10")
    else:
        raise

When it happens

Trigger: Running `inspect_sessions.py` with no positional thread ID and no `--list` flag; also occurs when the thread ID argument is an empty string or was dropped by a wrapper script.

Common situations: Forgetting the positional argument, quoting issues dropping an empty argument, or migration from older invocations that defaulted to listing.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Use either a thread ID or --list N, not both
• dcode: {message}
• Could not resolve {label} path {raw_path!r}: {exc}. Ensure t
• Error: Source agent '{source_agent}' not found or has no AGE
• enable_interpreter=True is not supported with a remote sandb

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