langchain-ai/deepagents · error · SystemExit

Thread not found: {value}

Error message

Thread not found: {value}

What it means

Raised by `_resolve_thread_id` in the thread-inspector CLI when a user-supplied thread ID (or prefix) matches no rows in the checkpointer's `thread_id` lookup (the SQL `LIKE 'value%'` query returns no matches). The script converts it to `SystemExit` with a non-zero status, so it's a controlled CLI failure, not a crash.

Source

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

def _resolve_thread_id(conn: sqlite3.Connection, value: str) -> str:
    exact = conn.execute(
        "SELECT 1 FROM checkpoints WHERE thread_id = ? AND checkpoint_ns = '' LIMIT 1",
        (value,),
    ).fetchone()
    if exact:
        return value
    escaped = value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
    rows = conn.execute(
        "SELECT DISTINCT thread_id FROM checkpoints "
        "WHERE checkpoint_ns = '' AND thread_id LIKE ? ESCAPE '\\' "
        "ORDER BY thread_id LIMIT 11",
        (escaped + "%",),
    ).fetchall()
    matches = [str(row[0]) for row in rows]
    if not matches:
        msg = f"Thread not found: {value}"
        raise SystemExit(msg)
    if len(matches) > 1:
        rendered = "\n".join(f"  {match}" for match in matches[:10])
        msg = f"Thread prefix is ambiguous:\n{rendered}"
        raise SystemExit(msg)
    return matches[0]


def _decode_metadata(
    value: object, warnings: list[str] | None = None
) -> dict[str, object]:
    if isinstance(value, bytes):
        try:
            value = value.decode("utf-8")
        except UnicodeDecodeError:
            if warnings is not None:
                warnings.append("Checkpoint metadata was not valid UTF-8.")
            return {}
    if not isinstance(value, str) or not value:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Run `inspect_sessions.py --list N` to enumerate existing thread IDs and pick the correct one
2. Verify you are pointing at the correct checkpointer/store database (right --db path or runtime environment)
3. Paste the full, unmodified thread ID rather than a hand-typed prefix
4. Check whether the thread still exists in LangSmith/backend (it may have been deleted or expired)

Example fix

// before
inspect_sessions.py e3a1f9   # typo, no match
// after
inspect_sessions.py --list 10  # find the right thread_id first

import subprocess, sys
result = subprocess.run(
    ["inspect_sessions.py", "--list", "100"], capture_output=True, text=True
)
known_ids = {line.strip() for line in result.stdout.splitlines() if line.strip()}
assert my_thread_id in known_ids, f"unknown thread: {my_thread_id}"

def thread_exists(thread_id: str, known: set[str]) -> bool:
    return bool(thread_id) and thread_id in known

try:
    run_inspector(thread_id)
except SystemExit as e:
    if "Thread not found" in str(e):
        list_threads_and_retry()
    else:
        raise

When it happens

Trigger: Running `inspect_sessions.py <id>` where the ID is a full or partial thread ID that does not exist in the checkpointer database: typo'd ID, wrong DB path, thread from a different project/environment, or a purged/expired thread.

Common situations: Copying a thread ID from logs of another environment, pointing --db at the wrong sqlite file, threads deleted by TTL cleanup, or truncating/copying IDs incorrectly (e.g. missing characters).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Thread prefix is ambiguous: {rendered}
• Error: Skill '{skill_name}' not found.
• dcode: {message}
• Could not resolve {label} path {raw_path!r}: {exc}. Ensure t
• Error: Source agent '{source_agent}' not found or has no AGE

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