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.

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
• Cannot extract symbols from file
• ❌ Health check failed
• No analyzable files found
• No symbol declaration found at the location of the regex…

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

Appendix: 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)