Symbol Not Found

Symptoms

• canopy_extract_symbol returns an empty result or “symbol not found”.
• canopy_search_symbols does not return a symbol you know exists in the codebase.
• canopy_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 canopy 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)	canopy 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 canopy 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

canopy status --repo .

Look for:

• Stale files: if greater than 0, run canopy 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:

canopy index . --with-search

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

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

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

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

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

canopy_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

Canopy 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. canopy_extract_symbol and canopy_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>/.canopy/config.toml
cat ~/.canopy/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:

canopy index . --full --with-search

Step 6: Check for dynamically generated symbols

Canopy 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 canopy_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 canopy_parse_file output after re-indexing.
• canopy status shows the file as indexed but the symbol is still missing.

Include the output of:

canopy status --repo .
canopy --version

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