oraios/serena · error · _HealthCheckFailure

FindSymbolTool returned no results

Error message

FindSymbolTool returned no results

What it means

Health check step 2 runs FindSymbolTool to locate a symbol by name. If find_symbol returns no results, serena raises `_HealthCheckFailure`, concluding the tooling is not functional even though the LS may be running. Note FindReferencingSymbols failures are only warned, but FindSymbol failure is fatal to the check.

Source

Thrown at src/serena/cli.py:1027

                    find_symbol_result = agent.execute_task(
                        lambda: find_symbol_tool.apply(symbol_name, relative_path=target_file, include_body=True)
                    )
                find_symbol_data = json.loads(find_symbol_result)
                log.info("FindSymbolTool found %d matches for symbol %s", len(find_symbol_data), symbol_name)

                # Test 3: FindReferencingSymbolsTool
                log.info("Testing FindReferencingSymbolsTool for symbol: %s", symbol_name)
                try:
                    with find_refs_tool.symbol_dict_grouper.disabled_context():
                        find_refs_result = agent.execute_task(lambda: find_refs_tool.apply(symbol_name, relative_path=target_file))
                        find_refs_data = json.loads(find_refs_result)
                        log.info("FindReferencingSymbolsTool found %d references for symbol %s", len(find_refs_data), symbol_name)
                except Exception as e:
                    log.warning("FindReferencingSymbolsTool failed for symbol %s: %s", symbol_name, str(e))

                # Verify tools worked as expected
                if not find_symbol_data:
                    raise ProjectCommands._HealthCheckFailure("FindSymbolTool returned no results")

                log.info("Health check completed successfully")

            # expected failures and unexpected exceptions are reported alike: both mean the project's
            # tooling is not functional, which is the single thing this command is asked to determine
            except Exception as e:
                log.exception("Health check failed with exception: %s", str(e))
                failure_reason = str(e)

            finally:
                click.echo(f"Log saved to: {log_file}")

        # the verdict is reported outside the checked region, so that a failure to write the report
        # cannot be mistaken for a failure of the check itself; the exit code lets callers
        # (CI, scripts) act on the verdict
        if failure_reason is None:
            click.echo("✅ Health check passed - All tools working correctly")
        else:

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Re-run `serena project index` to rebuild the symbol index, then re-run the health check.
2. Check serena logs for the underlying FindSymbolTool error/output.
3. Confirm the language server version is supported and fully operational (try find_symbol manually via `serena tools`).
4. Restart the health check / LS process to rule out a transient LS failure.

Example fix

// before
serena project health-check  # fails: stale index
// after
serena project index
serena project health-check

# ensure the index is fresh before health-checking
run(['serena', 'project', 'index'], check=True)

for attempt in range(2):
    try:
        run(['serena', 'project', 'health-check'], check=True)
        break
    except subprocess.CalledProcessError as e:
        if 'FindSymbolTool returned no results' in (e.stderr or '') and attempt == 0:
            run(['serena', 'project', 'index'], check=True)
            continue
        raise

When it happens

Trigger: `serena project health-check` selected a symbol from the overview but FindSymbolTool.query returned empty — e.g. the name_path resolution fails for that symbol kind, symbol was a variable/constructor without matches, or the LS index is stale.

Common situations: Stale or missing symbol index after files changed; LS partially functional (overview works, lookup doesn't); symbols nested so the default name_path doesn't resolve; transient LS errors swallowed upstream.

Related errors

• No symbols found in target file {target_file}
• No analyzable files found
• ❌ Health check failed: {failure_reason}
• Cannot extract symbols from file {relative_path}. Active lan
• No symbol declaration found at the location of the regex mat

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