{"record":{"id":"ee9bce697de53350","repo":"langchain-ai/deepagents","slug":"thread-prefix-is-ambiguous-rendered","errorCode":null,"errorMessage":"Thread prefix is ambiguous:\n{rendered}","messagePattern":"Thread prefix is ambiguous:\n(.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/built_in_skills/deepagents-thread-inspector/scripts/inspect_sessions.py","lineNumber":185,"sourceCode":"        (value,),\n    ).fetchone()\n    if exact:\n        return value\n    escaped = value.replace(\"\\\\\", \"\\\\\\\\\").replace(\"%\", \"\\\\%\").replace(\"_\", \"\\\\_\")\n    rows = conn.execute(\n        \"SELECT DISTINCT thread_id FROM checkpoints \"\n        \"WHERE checkpoint_ns = '' AND thread_id LIKE ? ESCAPE '\\\\' \"\n        \"ORDER BY thread_id LIMIT 11\",\n        (escaped + \"%\",),\n    ).fetchall()\n    matches = [str(row[0]) for row in rows]\n    if not matches:\n        msg = f\"Thread not found: {value}\"\n        raise SystemExit(msg)\n    if len(matches) > 1:\n        rendered = \"\\n\".join(f\"  {match}\" for match in matches[:10])\n        msg = f\"Thread prefix is ambiguous:\\n{rendered}\"\n        raise SystemExit(msg)\n    return matches[0]\n\n\ndef _decode_metadata(\n    value: object, warnings: list[str] | None = None\n) -> dict[str, object]:\n    if isinstance(value, bytes):\n        try:\n            value = value.decode(\"utf-8\")\n        except UnicodeDecodeError:\n            if warnings is not None:\n                warnings.append(\"Checkpoint metadata was not valid UTF-8.\")\n            return {}\n    if not isinstance(value, str) or not value:\n        return {}\n    try:\n        decoded = json.loads(value)\n    except ValueError:","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/built_in_skills/deepagents-thread-inspector/scripts/inspect_sessions.py#L167-L203","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a longer prefix (or the full thread ID) so exactly one thread matches","Pick the exact ID from the candidate list printed in the error message","Run `--list` to browse all threads and select the correct full ID"],"exampleFix":"// before\ninspect_sessions.py a1        # ambiguous\n// after\ninspect_sessions.py a1b2c3d4-e5f6-7890-abcd-ef0123456789","handlingStrategy":"validation","validationCode":"if sum(1 for t in all_thread_ids if t.startswith(prefix)) > 1:\n    raise ValueError(f\"prefix {prefix!r} is ambiguous; use a longer prefix\")","typeGuard":"def is_unique_prefix(prefix: str, ids: list[str]) -> bool:\n    return sum(1 for i in ids if i.startswith(prefix)) == 1","tryCatchPattern":"try:\n    run_inspector(prefix)\nexcept SystemExit as e:\n    if \"ambiguous\" in str(e):\n        candidates = [l.strip() for l in str(e).splitlines()[1:]]\n        run_inspector(candidates[0])\n    else:\n        raise","preventionTips":["Use at least 8+ characters of the thread ID as prefix","Prefer full UUIDs when available","Keep a mapping of thread IDs instead of abbreviating them"],"tags":["cli","ambiguity","thread-id"],"backgroundTag":"ambiguous-identifier","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}