oraios/serena · error · ValueError

name_path_pattern must not be empty or contain only wildcard

Error message

name_path_pattern must not be empty or contain only wildcards; consider using the overview tool

What it means

JetBrains find_symbol tool rejects a name_path_pattern that is empty or consists only of wildcard characters (e.g. '*' or '**'). Such a pattern would match everything, so the tool refuses it and points the caller to the dedicated symbols-overview tool, or (when a wildcard-only pattern is combined with an existing relative_path) automatically substitutes the overview tool's response.

Source

Thrown at src/serena/tools/jetbrains_tools.py:86

            about the symbol.
            Default False; info is never included for child symbols or if include_body is True.
        :param search_deps: If True, also search in project dependencies (e.g., libraries).
        :param max_matches: Maximum number of permitted matches. If exceeded, a shortened result is returned
             which allows refining the search. -1 (default) means no limit. Set to 1 if you search for a single symbol.
        :param max_answer_chars: max characters for the result (-1 for default). If exceeded, no content/a shortened result is returned.
        :return: symbols matching the name.
        """
        # check input
        # - pattern with only wildcards is invalid, but in some cases we delegate to the overview tool
        if name_path_pattern.replace("*", "").replace("/", "") == "":
            if relative_path:
                if self.project.relative_path_exists(relative_path, require_file=True):
                    overview_tool = self.agent.get_tool(JetBrainsGetSymbolsOverviewTool)
                    overview_response = overview_tool.apply(relative_path, depth=depth)
                    return self._wrapped_tool_response(
                        overview_response, f"Wildcard-only pattern not admitted; used {overview_tool.get_name()} instead"
                    )
            raise ValueError("name_path_pattern must not be empty or contain only wildcards; consider using the overview tool")

        if include_body:
            depth = 0  # ignore user-specified depth if body is requested

        name_path_pattern = self._sanitize_input_param(name_path_pattern)

        if relative_path:
            relative_path = self._sanitize_input_param(relative_path)
        if relative_path == ".":
            relative_path = None

        if relative_path is not None and relative_path.startswith(jb.JB_EXTERNAL_FILE_PREFIX):
            search_deps = True

        with JetBrainsPluginClient.from_project(self.project) as client:
            if include_body:
                include_quick_info = False
                include_documentation = False

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Call the symbols-overview tool (JetBrainsGetSymbolsOverviewTool) with the file's relative_path instead of find_symbol
2. Include at least one non-wildcard literal substring in name_path_pattern, e.g. 'MyClass*' instead of '*'
3. If you need a directory-wide listing, pass a real relative_path so the wildcard-only branch can redirect to the overview tool automatically

Example fix

// before
find_symbol.apply(name_path_pattern='*', relative_path='src/foo.py')
// raises ValueError

// after
overview = agent.get_tool(JetBrainsGetSymbolsOverviewTool)
result = overview.apply('src/foo.py', depth=1)
# or
find_symbol.apply(name_path_pattern='MyClass*', relative_path='src/foo.py')

def valid_name_pattern(p: str) -> bool:
    stripped = p.replace('*', '').replace('?', '')
    return bool(p and p.strip() and stripped.strip())
if not valid_name_pattern(name_path_pattern):
    result = overview_tool.apply(relative_path, depth=depth)
else:
    result = find_symbol_tool.apply(name_path_pattern=name_path_pattern, ...)

def is_literal_pattern(p: str | None) -> bool:
    return isinstance(p, str) and bool(p.strip(' *?'))

When it happens

Trigger: Calling JetBrainsFindSymbolTool.apply with name_path_pattern='' or name_path_pattern='*' / '**' (only wildcards, no literal text), or omitting the parameter entirely so sanitization leaves it empty.

Common situations: LLM/agent calls find_symbol wanting 'all symbols in a file' instead of a specific name; refactoring a caller that previously passed a bare '*'; building a dynamic query where the user-supplied name part was stripped out leaving only wildcards.

Related errors

• Expected a file path, but got a directory path: {relative_pa
• Cannot insert after this symbol (not a function, class or me
• Cannot use both fixed_tools and excluded_tools/included_opti
• Unknown language backend '{backend_str}': valid values are {
• Invalid line_ending: {value!r}. Valid values are: {valid}

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/c1df8a2493cc598f. Report an issue: GitHub.