Symbol Not Found

Symptoms

• forge_extract_symbol returns an empty result or “symbol not found”.
• forge_search_symbols does not return a symbol you know exists in the codebase.
• forge_parse_file returns an empty symbols list for a file that clearly has functions and classes.
• A recently added function is not findable after indexing.

---

Likely Causes

Cause	Indicator
File has not been indexed yet	File was added after the last forge index run
Symbol is in an unsupported language	Language is not TypeScript, JavaScript, Rust, Python, or Go
Index is stale (file was modified after indexing)	forge status shows stale files
Symbol is dynamically generated or macro-expanded	Pattern does not match tree-sitter AST nodes
File is excluded by ignored_paths or .gitignore	File does not appear in forge status file count
Symbol name mismatch (exported vs internal name)	Searching for import alias instead of definition name

---

Step-by-Step Fix

Step 1: Check the index status

forge status --repo .

Look for:

• Stale files: if greater than 0, run forge index . to update.
• Files indexed: compare to the actual file count in your codebase.

Step 2: Re-index and retry

Run an incremental index to pick up any recent file changes:

forge index . --with-search

Then retry the symbol lookup. For forge_extract_symbol, the MCP call:

{
  "file": "src/api/handler.ts",
  "symbol": "handleRequest"
}

Step 3: Use forge_parse_file to verify the symbol exists in the index

Before using forge_extract_symbol, confirm the file is indexed and the symbol is visible:

{
  "file": "src/api/handler.ts"
}

forge_parse_file returns all symbols found in the file. If the symbol you expect is not in the list, the extractor may not recognize its syntax.

Step 4: Check language support

Forge supports these languages:

Language	Extensions
TypeScript	.ts, .tsx
JavaScript	.js, .jsx, .mjs, .cjs
Rust	.rs
Python	.py
Go	.go

Files in other languages are indexed for search (text content) but symbols are not extracted. forge_extract_symbol and forge_parse_file return empty results for unsupported languages.

Step 5: Check for file exclusions

Verify the file is not excluded from indexing:

# Check if the file path matches any ignored_paths patterns
cat <repo>/.forge/config.toml
cat ~/.forge/config.toml
cat <repo>/.gitignore

If the file matches an ignored_paths pattern, remove the pattern or add a negation. After changing the config, run a full re-index:

forge index . --full --with-search

Step 6: Check for dynamically generated symbols

Forge uses static AST analysis (tree-sitter). It cannot extract:

• Symbols generated by macros or metaprogramming
• Functions defined in eval strings
• Rust proc-macro-generated items (only the macro call site is indexed)
• TypeScript decorators that produce new symbols at runtime

For these cases, use forge_search to find the relevant source location instead.

Step 7: Verify the symbol name exactly

Symbol lookup is case-sensitive and matches the definition name, not the import alias:

handler.ts

export function handleRequest() { ... }   // Symbol name: "handleRequest"

// consumer.ts
import { handleRequest as processReq } from './handler';  // Alias: "processReq"

Use the definition name (handleRequest), not the alias.

---

When to Escalate

Contact support at [email protected] if:

• A symbol in a supported language does not appear in forge_parse_file output after re-indexing.
• forge status shows the file as indexed but the symbol is still missing.

Include the output of:

forge status --repo .
forge --version

And the exact file path and symbol name you are searching for.