gh-fryrai-baml-claude-skill-baml-codegen/TROUBLESHOOTING.md

BAML Code Generation Skill - Troubleshooting Guide

Version: 1.0.0 Last Updated: 2025-01-25

Common Issues

1. MCP Server Unavailable

Error: MCP server unavailable

Causes:

• MCP server not installed
• Network connectivity issues
• Server configuration problems

Solutions:

1. Verify MCP server installation:

   claude mcp add "baml_Docs" --scope user -- npx -y mcp-remote https://gitmcp.io/BoundaryML/baml
   

2. Check MCP server status in Claude Code settings

3. If unavailable, skill will use cached patterns (offline mode)

   • Functionality: ~80% (cached patterns only)
   • Warning: "Operating in offline mode with cached patterns"

Workaround: Continue using cached patterns, manually refresh when connection restored

---

2. Pattern Not Found

Error: No matching pattern found for requirement

Causes:

• Requirement too vague or novel
• No similar examples in repository
• Cache miss with MCP unavailable

Solutions:

1. Provide more specific requirements:

   • Bad: "Process documents"
   • Good: "Extract invoice data from images including line items and totals"

2. Specify pattern category:

   • "Generate BAML extraction function for..."
   • "Create BAML classification function for..."

3. Use generic template: Skill will automatically use generic template for category

---

3. Generated Code Validation Failed

Error: Syntax error in generated code or Type resolution failed

Causes:

• Complex nested types
• Circular type dependencies
• Invalid BAML syntax in generated code

Solutions:

1. Check validation errors: Skill provides detailed diagnostics

2. Simplify requirements: Break complex requirements into smaller parts

3. Regenerate with different approach: Retry generation

4. Manual fix: Apply suggested corrections from validation output

---

4. Compilation Errors

Error: Generated code doesn't compile

Causes:

• Missing type definitions
• Invalid function signatures
• Client configuration errors

Solutions:

1. Run BAML compiler:

   baml-cli generate
   

2. Check error messages: BAML compiler provides specific line numbers

3. Verify all types are defined: Check that referenced types exist

4. Check client configuration: Ensure provider/model names are correct

---

5. Multimodal Functions Not Working

Error: Model reports "I don't see the image"

Cause: Missing image parameter in prompt (THE #1 BAML GOTCHA!)

Solution: CRITICAL: Ensure image parameter is included in prompt body:

// WRONG - Image not visible to model
function ExtractFromImage(page_image: image) -> Result {
  client VisionModel
  prompt #"
    Extract data from this image.
    {{ ctx.output_format }}
  "#
}

// CORRECT - Image visible to model
function ExtractFromImage(page_image: image) -> Result {
  client VisionModel
  prompt #"
    Extract data from this image.

    {{ page_image }}  // ← MUST INCLUDE THIS!

    {{ ctx.output_format }}
  "#
}

Reference: See CLAUDE.md BAML Development section for detailed multimodal guidance

---

6. Cache Issues

Error: Cache write failed or Cache corrupted

Causes:

• File system permissions
• Corrupted cache file
• Disk space issues

Solutions:

1. Check permissions: Ensure write access to baml-claude-skill/cache/

2. Clear cache:

   rm baml-claude-skill/cache/*.json
   

   Skill will rebuild cache automatically

3. Check disk space: Ensure sufficient space available

---

7. Performance Issues

Error: Generation taking too long

Causes:

• Complex requirements
• MCP query delays
• Large pattern library

Solutions:

1. Simplify requirements: Break into smaller tasks

2. Use cached patterns: Subsequent generations are faster

3. Check MCP connectivity: Slow network affects performance

Expected Times:

• Simple function: <5s
• Complex system: <30s

---

8. Test Generation Incomplete

Error: Tests not covering all functions

Causes:

• Complex function signatures
• Unknown input/output types
• Framework not supported

Solutions:

1. Review generated tests: Add missing test cases manually

2. Specify test requirements explicitly:

   • "Include edge cases for empty input"
   • "Add tests for error handling"

3. Supported frameworks:

   • Python: pytest
   • TypeScript: Jest
   • Ruby: RSpec

---

9. Integration Code Not Working

Error: Framework integration has errors

Causes:

• Framework version mismatch
• Missing dependencies
• Incorrect configuration

Solutions:

1. Check framework version: Ensure compatible version installed

2. Install dependencies:

   # Python
   pip install baml-py fastapi uvicorn
   
   # TypeScript
   npm install @boundaryml/baml
   

3. Review generated code: May need minor adjustments for your setup

4. Supported frameworks:

   • Python: FastAPI, Flask, Django
   • TypeScript: Next.js, Express, NestJS
   • Ruby: Rails, Sinatra
   • Java: Spring Boot
   • Go: Gin, Echo
   • C#: ASP.NET Core

---

10. Cost Exceeds Target

Error: Generation cost above $0.02 target

Causes:

• Large prompt sizes
• Multiple MCP queries
• Complex nested types

Solutions:

1. Apply aggressive optimization:

   • Request optimization level: "aggressive"

2. Simplify types: Reduce nested structures

3. Use caching: Cached generations are cheaper

4. Monitor metrics: Check token counts in metadata

---

Error Codes

Code	Meaning	Solution
MCP-001	MCP server unavailable	Check installation, use cached patterns
MCP-002	MCP query timeout	Retry, check network
MCP-003	MCP rate limited	Wait, implement backoff
PAT-001	Pattern not found	Provide more specific requirements
PAT-002	Pattern validation failed	Use alternative pattern
GEN-001	Code generation failed	Retry with different approach
GEN-002	Syntax validation failed	Check error details, manual fix
GEN-003	Type resolution failed	Define missing types
CACHE-001	Cache write error	Check permissions
CACHE-002	Cache corrupted	Clear and rebuild cache
TEST-001	Test generation incomplete	Review and complete manually
INT-001	Integration code error	Check framework compatibility

---

Debug Mode

Enable detailed logging:

Request: "Enable debug mode for BAML generation"

Claude will output:
- Detailed MCP queries
- Pattern matching scores
- Code generation steps
- Validation details
- Performance metrics

---

Getting Help

1. Check this guide for common issues

2. Review generated metadata for clues:

   • Token counts
   • Pattern used
   • Validation errors

3. Enable debug mode for detailed logs

4. Check BAML documentation:

   • Skill queries MCP automatically
   • Or visit: https://docs.boundaryml.com

5. Report issues:

   • Provide: requirement text, error message, generated code
   • Include: metadata and debug logs if available

---

Tips for Success

Writing Good Requirements

Do:

• Be specific about data to extract/classify
• Mention input types (image, text, pdf)
• Specify validation rules if needed
• Include multimodal keywords ("image", "vision") when relevant

Don't:

• Be too vague ("process documents")
• Omit input/output types
• Assume default behavior

Optimizing Performance

1. Use caching: Repeated similar requests are faster
2. Batch related requests: Generate multiple related functions at once
3. Simplify first: Start simple, add complexity iteratively
4. Cache warmup: First request slower (cold start)

Ensuring Quality

1. Review generated code: Always validate output
2. Run tests: Execute generated tests to verify
3. Check compilation: Run baml-cli generate
4. Iterate: Refine requirements based on output

---

Need More Help?

Check the quickstart guide for usage examples.