Initial commit
This commit is contained in:
Zhongwei Li
345
TROUBLESHOOTING.md
Normal file
345
TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# 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:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
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:
|
||||
|
||||
```baml
|
||||
// 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**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
# 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](../specs/001-baml-codegen-skill/quickstart.md) for usage examples.
|
||||
Reference in New Issue
Block a user