{"record":{"id":"a16b876370c08d0e","repo":"github/copilot-sdk","slug":"copilotclient-is-in-mode-empty-but-create-sessio","errorCode":null,"errorMessage":"CopilotClient is in mode='empty' but create_session was called without available_tools. Empty mode requires every session to explicitly opt into the tools it wants — e.g. ToolSet().add_builtin(BUILTIN_TOOLS_ISOLATED).","messagePattern":"CopilotClient is in mode='empty' but create_session was called without available_tools\\. Empty mode requires every session to explicitly opt into the tools it wants — e\\.g\\. ToolSet\\(\\)\\.add_builtin\\(BUILTIN_TOOLS_ISOLATED\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/copilot/_mode.py","lineNumber":366,"sourceCode":"    is_uri_connection: bool,\n) -> None:\n    if mode != \"empty\":\n        return\n    if base_directory or session_fs_set or is_uri_connection:\n        return\n    raise ValueError(\n        \"CopilotClient(mode='empty') requires base_directory, session_fs, \"\n        \"or a UriRuntimeConnection. Empty mode needs explicit per-tenant \"\n        \"storage and won't fall back to ~/.copilot.\"\n    )\n\n\ndef _require_available_tools_for_empty_mode(\n    mode: CopilotClientMode | None,\n    available_tools: list[str] | None,\n) -> None:\n    if mode == \"empty\" and available_tools is None:\n        raise ValueError(\n            \"CopilotClient is in mode='empty' but create_session was called \"\n            \"without available_tools. Empty mode requires every session to \"\n            \"explicitly opt into the tools it wants — e.g. \"\n            \"ToolSet().add_builtin(BUILTIN_TOOLS_ISOLATED).\"\n        )\n","sourceCodeStart":348,"sourceCodeEnd":372,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/_mode.py#L348-L372","documentation":"In mode='empty' every session must explicitly declare which tools it may use; there is no implicit default tool set. create_session (and resume_session) without available_tools is rejected so no session accidentally inherits tools in an isolated environment.","triggerScenarios":"Calling client.create_session() or client.resume_session(...) on a CopilotClient constructed with mode='empty' without passing available_tools (it remains None) — checked in _require_available_tools_for_empty_mode.","commonSituations":"Code shared between default-mode and empty-mode clients calls create_session uniformly; examples written for the default mode are reused in isolated multi-tenant deployments; a refactor moved the client into empty mode but session-creation call sites were not updated.","solutions":["Pass available_tools=ToolSet().add_builtin(BUILTIN_TOOLS_ISOLATED).to_list() to create_session","Build the explicit per-session ToolSet your tenant requires and pass it on every create/resume","If sessions should not be restricted, switch the client back to a non-'empty' mode","Wrap session creation in a helper that always injects the tool filter for empty mode"],"exampleFix":"// before\nsession = client.create_session()\n\n// after\nsession = client.create_session(\n    available_tools=ToolSet().add_builtin(BUILTIN_TOOLS_ISOLATED).to_list()\n)","handlingStrategy":"validation","validationCode":"if client.mode == \"empty\" and available_tools is None:\n    raise ValueError(\"empty mode requires available_tools on every session\")","typeGuard":"def session_call_is_valid(mode, available_tools) -> bool:\n    return mode != \"empty\" or available_tools is not None","tryCatchPattern":"try:\n    session = client.create_session()\nexcept ValueError as e:\n    if \"without available_tools\" in str(e):\n        session = client.create_session(available_tools=default_tool_set().to_list())","preventionTips":["Route all session creation through a helper that always passes available_tools","Define a module-level DEFAULT_EMPTY_MODE_TOOLS constant and reuse it","Update session-creation call sites whenever a client switches to mode='empty'","Check the client mode in tests that exercise create_session/resume_session"],"tags":["configuration","python","tools","isolation"],"backgroundTag":"missing-required-option","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}