{"record":{"id":"84f2a11cf0c5214a","repo":"langchain-ai/deepagents","slug":"preloaded-thread-history-requires-resume-thread-id","errorCode":null,"errorMessage":"preloaded thread history requires resume_thread_id","messagePattern":"preloaded thread history requires resume_thread_id","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/app.py","lineNumber":23861,"sourceCode":"            resume_thread_id: Existing thread to resume under the new agent.\n                `None` starts a fresh thread, preserving normal agent-picker\n                behavior.\n            preloaded_payload: History fetched before a combined agent/thread\n                transition mutates the current session.\n            persist_default_agent: Whether the switch should become the saved\n                default agent. One-off thread resumes leave it unchanged.\n\n        Returns:\n            `True` when the new agent is running and the requested transition\n            completed, otherwise `False`.\n\n        Raises:\n            ValueError: If a preloaded history payload is supplied without a\n                thread to resume.\n        \"\"\"\n        if preloaded_payload is not None and resume_thread_id is None:\n            msg = \"preloaded thread history requires resume_thread_id\"\n            raise ValueError(msg)\n\n        from deepagents_code._env_vars import SERVER_ENV_PREFIX\n        from deepagents_code.client.remote_client import RemoteAgent as _RemoteAgent\n\n        def _build_agent(url: str) -> Any:  # noqa: ANN401  # see docstring\n            \"\"\"Build a new `RemoteAgent` typed as `Any`.\n\n            Returns `Any` so `self._agent`'s attribute type stays aligned\n            with the permissive type the startup path assigns, avoiding a\n            union that would trip call-site type checks on\n            `aget_state(config)` et al.\n\n            Args:\n                url: Server base URL to point the new client at.\n\n            Returns:\n                A fresh `RemoteAgent`, exposed as `Any`.\n            \"\"\"","sourceCodeStart":23843,"sourceCodeEnd":23879,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/app.py#L23843-L23879","documentation":"When constructing a remote agent, supplying a preloaded thread-history payload (`preloaded_payload`) without also naming the thread via `resume_thread_id` is ambiguous — there is no thread to attach the history to — so a ValueError is raised in the setup path.","triggerScenarios":"Calling the remote-agent builder with `preloaded_payload=<history>` but `resume_thread_id=None`, e.g. restoring cached conversation state from disk after losing the thread ID, or passing the payload from one code path and the thread ID from another.","commonSituations":"Session restore/undo features that persisted history but not the thread ID; mismatched argument plumbing between a UI layer and the agent factory.","solutions":["Pass resume_thread_id together with preloaded_payload","Persist and reload the thread ID alongside the history payload","If there is no thread to resume, omit preloaded_payload and start a fresh thread"],"exampleFix":"// before\nbuild_agent(url, preloaded_payload=history)\n// after\nbuild_agent(url, preloaded_payload=history, resume_thread_id=thread_id)","handlingStrategy":"validation","validationCode":"if preloaded_payload is not None and resume_thread_id is None:\n    raise ValueError(\"cannot preload history without a thread id to resume\")","typeGuard":"def can_build_remote_agent(preloaded_payload: object, resume_thread_id: str | None) -> bool:\n    return preloaded_payload is None or resume_thread_id is not None","tryCatchPattern":"try:\n    agent = build_remote_agent(url, preloaded_payload=history, resume_thread_id=thread_id)\nexcept ValueError as exc:\n    logger.error(\"session restore failed: %s\", exc)\n    agent = build_remote_agent(url)  # fresh thread fallback","preventionTips":["Persist thread_id together with the history payload in the same record","Restore both atomically; refuse partial restores","Add an assertion where session state is serialized"],"tags":["remote-agent","thread-state","argument-validation"],"backgroundTag":"missing-required-field","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}