oraios/serena · error · _HealthCheckFailure

No symbols found in target file {target_file}

Error message

No symbols found in target file {target_file}

What it means

Health check step 1 runs GetSymbolsOverviewTool on the chosen target file. If the language server returns an empty symbol list, serena raises `_HealthCheckFailure` because subsequent symbol-lookup tests cannot proceed. This indicates the language server is up but not producing symbols for that file.

Source

Thrown at src/serena/cli.py:987

                            break
                    except (OSError, FileNotFoundError):
                        continue

                if not target_file:
                    raise ProjectCommands._HealthCheckFailure("No analyzable files found")

                # Get tools from agent
                overview_tool = agent.get_tool(GetSymbolsOverviewTool)
                find_symbol_tool = agent.get_tool(FindSymbolTool)
                find_refs_tool = agent.get_tool(FindReferencingSymbolsTool)

                # Test 1: Get symbols overview
                log.info("Testing GetSymbolsOverviewTool on file: %s", target_file)
                overview_data = agent.execute_task(lambda: overview_tool.get_symbol_overview(target_file))
                log.info(f"GetSymbolsOverviewTool returned: {overview_data}")

                if not overview_data:
                    raise ProjectCommands._HealthCheckFailure(f"No symbols found in target file {target_file}")

                # Extract suitable symbol (prefer class or function over variables)
                preferred_kinds = {SymbolKind.Class.name, SymbolKind.Function.name, SymbolKind.Method.name, SymbolKind.Constructor.name}
                selected_symbol = None
                for symbol in overview_data:
                    if symbol.get("kind") in preferred_kinds:
                        selected_symbol = symbol
                        break

                # If no preferred symbol found, use first available
                if not selected_symbol:
                    selected_symbol = overview_data[0]
                    log.info("No class or function found, using first available symbol")

                symbol_name = selected_symbol["name"]
                symbol_kind = selected_symbol["kind"]
                log.info("Using symbol for testing: %s (kind: %s)", symbol_name, symbol_kind)

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Ensure the project contains a real source file with at least one class, function, or method.
2. Verify the language server for the project language is installed and starts without errors (check serena logs).
3. Re-run `serena project index` to refresh the symbol cache, then re-run the health check.
4. Try the health check on a known-good file in the project.

Example fix

// before (target file is empty stubs.py)
# (nothing in stubs.py)
// after
# stubs.py
def hello():
    return 'hi'
# re-run: serena project health-check

from pathlib import Path
target = Path('main.py')
content = target.read_text()
if not any(ln.strip() and not ln.strip().startswith(('#', '//', 'import', 'from')) for ln in content.splitlines()):
    raise SystemExit('Target file has no code; pick a file with real definitions')

try:
    run(['serena', 'project', 'health-check'], check=True)
except subprocess.CalledProcessError as e:
    if 'No symbols found' in e.stderr:
        print('Language server returned no symbols; check LS installation/logs')

When it happens

Trigger: `serena project health-check` selected a target file whose overview returns an empty list — e.g. a file with no classes/functions/methods/variables the LS reports, an empty file, or an LS that fails silently to parse it.

Common situations: Target file is empty or only comments/imports; the language server doesn't support that file type; the file is a config/markup file that slipped through the analyzable-file search; a broken LS install returning no symbols.

Related errors

• FindSymbolTool returned no results
• No analyzable files found
• ❌ Health check failed: {failure_reason}
• Cannot apply setup for client '{client}' (not found or not f
• Failed to set up Serena for {client}.

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