{"record":{"id":"5aa888f9bb38357d","repo":"JuliusBrussee/caveman","slug":"max-loaded-tools-must-be-at-least-the-always-load","errorCode":null,"errorMessage":"max_loaded_tools must be at least the always_load tool count","messagePattern":"max_loaded_tools must be at least the always_load tool count","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"packages/sdk/python/caveman_cloud/core.py","lineNumber":664,"sourceCode":"                                  calls the server to load relevant tools on demand.\n\n        Returns a handle with ``.strategy``, ``.initial`` (a ``list[CaveTool]``),\n        and ``.search(query, *, max_tools, context, workflow, ranker)`` which\n        hits the gateway and returns a :class:`ToolSearchResult`. Mirrors the\n        TypeScript ``cave.tools({ catalog, strategy })``.\n        \"\"\"\n        if strategy not in {\"all\", \"deferred\"}:\n            raise ValueError(\"strategy must be all or deferred\")\n        if isinstance(initial_tool_count, bool) or not isinstance(initial_tool_count, int) or initial_tool_count < 0:\n            raise ValueError(\"initial_tool_count must be a non-negative integer\")\n        if max_loaded_tools is not None and (isinstance(max_loaded_tools, bool) or not isinstance(max_loaded_tools, int) or max_loaded_tools < 1):\n            raise ValueError(\"max_loaded_tools must be a positive integer\")\n        if strategy == \"all\":\n            initial = list(catalog)\n        else:\n            always = [t for t in catalog if t.always_load]\n            if max_loaded_tools is not None and len(always) > max_loaded_tools:\n                raise ValueError(\"max_loaded_tools must be at least the always_load tool count\")\n            lazy = [t for t in catalog if not t.always_load]\n            lazy_limit = initial_tool_count if max_loaded_tools is None else min(initial_tool_count, max_loaded_tools - len(always))\n            initial = always + lazy[:lazy_limit]\n        return _ToolsHandle(self, catalog, strategy, initial, max_loaded_tools)\n\n    def tool_search(\n        self,\n        tools: list[CaveTool],\n        query: str,\n        *,\n        context: str | None = None,\n        max_tools: int | None = None,\n        workflow: str | None = None,\n        ranker: str | None = None,\n        session_id: str | None = None,\n    ) -> ToolSearchResult:\n        \"\"\"POST the tool catalog + query to the gateway's /sdk/v1/tool-search endpoint.\n","sourceCodeStart":646,"sourceCodeEnd":682,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/sdk/python/caveman_cloud/core.py#L646-L682","documentation":"Error \"max_loaded_tools must be at least the always_load tool count\" thrown in JuliusBrussee/caveman.","triggerScenarios":"Thrown at packages/sdk/python/caveman_cloud/core.py:664 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Raise max_loaded_tools to at least the always_load tool count."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}