JuliusBrussee/caveman · error · ValueError

max_loaded_tools must be at least the always_load tool count

Error message

max_loaded_tools must be at least the always_load tool count

What it means

Error "max_loaded_tools must be at least the always_load tool count" thrown in JuliusBrussee/caveman.

Source

Thrown at packages/sdk/python/caveman_cloud/core.py:664

                                  calls the server to load relevant tools on demand.

        Returns a handle with ``.strategy``, ``.initial`` (a ``list[CaveTool]``),
        and ``.search(query, *, max_tools, context, workflow, ranker)`` which
        hits the gateway and returns a :class:`ToolSearchResult`. Mirrors the
        TypeScript ``cave.tools({ catalog, strategy })``.
        """
        if strategy not in {"all", "deferred"}:
            raise ValueError("strategy must be all or deferred")
        if isinstance(initial_tool_count, bool) or not isinstance(initial_tool_count, int) or initial_tool_count < 0:
            raise ValueError("initial_tool_count must be a non-negative integer")
        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):
            raise ValueError("max_loaded_tools must be a positive integer")
        if strategy == "all":
            initial = list(catalog)
        else:
            always = [t for t in catalog if t.always_load]
            if max_loaded_tools is not None and len(always) > max_loaded_tools:
                raise ValueError("max_loaded_tools must be at least the always_load tool count")
            lazy = [t for t in catalog if not t.always_load]
            lazy_limit = initial_tool_count if max_loaded_tools is None else min(initial_tool_count, max_loaded_tools - len(always))
            initial = always + lazy[:lazy_limit]
        return _ToolsHandle(self, catalog, strategy, initial, max_loaded_tools)

    def tool_search(
        self,
        tools: list[CaveTool],
        query: str,
        *,
        context: str | None = None,
        max_tools: int | None = None,
        workflow: str | None = None,
        ranker: str | None = None,
        session_id: str | None = None,
    ) -> ToolSearchResult:
        """POST the tool catalog + query to the gateway's /sdk/v1/tool-search endpoint.

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Raise max_loaded_tools to at least the always_load tool count.

When it happens

Trigger: Thrown at packages/sdk/python/caveman_cloud/core.py:664 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/5aa888f9bb38357d. Report an issue: GitHub.