Troubleshooting

Common issues when using chisel and how to resolve them.

Parse Errors

"parse: expected..."

Symptom: Go provider returns parse error.

Cause: Source code has syntax errors.

Solution: The Go provider requires valid Go syntax. Unlike tree-sitter providers, it cannot recover from errors.

// This fails
source := []byte("func broken( {")
chunks, err := provider.Chunk(ctx, "test.go", source)
// err: parse: expected ')', found '{'

// Fix the syntax first
source := []byte("func working() {}")

Empty chunks from tree-sitter

Symptom: TypeScript/Python/Rust provider returns empty slice.

Cause: File contains only syntax errors or unsupported constructs.

Solution: Tree-sitter can parse partially valid code, but completely malformed files may yield no extractable chunks. Check that your source is valid for the target language.

Import Issues

"cannot find package"

Symptom: Import fails for a provider.

Cause: Provider not installed.

Solution: Install the specific provider:

go get github.com/zoobz-io/chisel/golang
go get github.com/zoobz-io/chisel/typescript

CGO errors with tree-sitter

Symptom: Build fails with CGO errors when importing TypeScript/Python/Rust providers.

Cause: Tree-sitter requires CGO.

Solution:

1. Ensure CGO is enabled: CGO_ENABLED=1
2. Install a C compiler (gcc, clang)
3. On macOS: xcode-select --install
4. On Linux: apt install build-essential or equivalent

If you can't use CGO, stick to the Go and Markdown providers which have zero external dependencies.

Chunker Issues

"no provider for language"

Symptom: Chunker.Chunk() returns error.

Cause: No provider registered for the requested language.

Solution: Register a provider when creating the chunker:

// Wrong: no providers
c := chisel.New()
chunks, err := c.Chunk(ctx, chisel.Go, "main.go", source)
// err: no provider for language: go

// Right: register providers
c := chisel.New(
    golang.New(),
    typescript.New(),
)

Wrong language specified

Symptom: Chunks don't match expected structure.

Cause: Language doesn't match file content.

Solution: Ensure the language matches the source:

// Wrong: TypeScript source with Go language
c.Chunk(ctx, chisel.Go, "app.ts", tsSource)

// Right: match language to content
c.Chunk(ctx, chisel.TypeScript, "app.ts", tsSource)

Unexpected Chunk Output

Missing chunks

Symptom: Expected function/class not in output.

Possible causes:

1. Nested in unexpected structure — Check if it's inside a block we don't walk
2. Anonymous construct — Arrow functions may use <anonymous>
3. Language-specific behavior — Check Providers Guide

Debug approach:

chunks, _ := provider.Chunk(ctx, filename, source)
for _, c := range chunks {
    fmt.Printf("%s %s (lines %d-%d) ctx=%v\n",
        c.Kind, c.Symbol, c.StartLine, c.EndLine, c.Context)
}

Unexpected kind

Symptom: Struct shows as class, trait shows as interface.

Cause: Chisel normalizes language constructs to semantic kinds.

Solution: This is intentional. See Concepts: Kinds for the mapping rationale.

Missing context

Symptom: Method has empty Context slice.

Cause: Method is at top level, not inside a class/impl block.

Solution: Context only applies to nested constructs:

// No context (top-level)
func TopLevel() {}

// Has context
type Service struct{}
func (s *Service) Method() {}  // Context: ["type Service"]

Performance Issues

Slow parsing

Symptom: Chunking takes too long.

Possible causes:

1. Very large files — Tree-sitter is O(n) but constant factors matter
2. Many small files — Provider creation overhead

Solutions:

1. Reuse providers across files (they're stateless and thread-safe)
2. For very large files, consider pre-splitting
3. Use Go/Markdown providers where possible (faster than tree-sitter)

High memory usage

Symptom: Memory grows when processing many files.

Solution: Chunks hold copies of source content. If you're processing many files:

for _, file := range files {
    chunks, _ := provider.Chunk(ctx, file.Name, file.Content)
    process(chunks)
    // chunks go out of scope here, eligible for GC
}

Don't accumulate all chunks in memory if you can process them incrementally.

Getting Help

If you encounter an issue not covered here:

1. Check GitHub Issues
2. Open a new issue with:
   • Go version
   • Chisel version
   • Minimal reproduction
   • Expected vs actual output

Next Steps

• Providers Guide — Language-specific behavior
• Architecture — How parsing works