langchain-ai/deepagents · error · SystemExit

Thread prefix is ambiguous: {rendered}

Error message

Thread prefix is ambiguous:
{rendered}

What it means

Raised by `_resolve_thread_id` when a thread-ID prefix matches more than one row (more than 10 by the LIMIT 11 check). The script refuses to guess and exits, listing up to 10 candidate thread IDs so the user can disambiguate.

Source

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

        (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:
        return {}
    try:
        decoded = json.loads(value)
    except ValueError:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Use a longer prefix (or the full thread ID) so exactly one thread matches
2. Pick the exact ID from the candidate list printed in the error message
3. Run `--list` to browse all threads and select the correct full ID

Example fix

// before
inspect_sessions.py a1        # ambiguous
// after
inspect_sessions.py a1b2c3d4-e5f6-7890-abcd-ef0123456789

if sum(1 for t in all_thread_ids if t.startswith(prefix)) > 1:
    raise ValueError(f"prefix {prefix!r} is ambiguous; use a longer prefix")

def is_unique_prefix(prefix: str, ids: list[str]) -> bool:
    return sum(1 for i in ids if i.startswith(prefix)) == 1

try:
    run_inspector(prefix)
except SystemExit as e:
    if "ambiguous" in str(e):
        candidates = [l.strip() for l in str(e).splitlines()[1:]]
        run_inspector(candidates[0])
    else:
        raise

When it happens

Trigger: Passing a short or shared prefix to `inspect_sessions.py <prefix>` where multiple persisted threads begin with those characters, e.g. many UUIDs sharing the first few hex digits.

Common situations: Abbreviating a thread ID to a few characters out of habit; batch-generated runs whose UUIDs coincidentally share a prefix; searching with a very short prefix like a single character.

Related errors

• Thread not found: {value}
• 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/ee9bce697de53350. Report an issue: GitHub.