Troubleshooting Guide
Solutions for common issues and debugging strategies for Claif.
Common Installation Issues
Module Not Found Errors
ModuleNotFoundError: No module named 'claif'
Solutions:
- Verify installation:
uv pip list | grep claif
- Check Python environment:
which python
- Reinstall:
uv pip uninstall claif && uv pip install claif
- Use virtual environment:
uv venv && source .venv/bin/activate
Provider Package Issues
ProviderError: No providers found
Solutions:
- Install a provider:
uv pip install claif_gem
- Check provider registration:
claif list
- Verify entry points:
python -c "import claif; print(claif.providers)"
Configuration Problems
API Key Issues
ConfigurationError: API key not found for provider 'claude'
Solutions:
- Set environment variable:
export ANTHROPIC_API_KEY=your_key
- Use config command:
claif config
- Check config file:
cat ~/.claif/config.toml
- Verify key validity: Test with provider’s official tools
Configuration File Errors
ValidationError: Invalid configuration format
Solutions:
- Check TOML syntax: Use online TOML validator
- Reset configuration:
rm ~/.claif/config.toml && claif config
- Use example config: Copy from documentation
- Check file permissions:
ls -la ~/.claif/
Provider-Specific Issues
Claude Provider (claif_cla
)
Hanging requests:
- Check network connectivity
- Verify API key permissions
- Increase timeout:
--timeout 300
- Use debug mode:
--verbose
Tool approval issues:
- Check approval strategy in config
- Use auto-approve mode cautiously
- Review tool permissions
Gemini Provider (claif_gem
)
CLI not found:
TransportError: Gemini CLI not found
Solutions:
- Install Gemini CLI: Follow Google’s installation guide
- Set CLI path:
export GEMINI_CLI_PATH=/usr/local/bin/gemini
- Verify installation:
which gemini
- Check PATH:
echo $PATH
Subprocess hanging:
- Use shorter prompts
- Check CLI arguments
- Increase timeout settings
- Verify CLI version compatibility
Codex Provider (claif_cod
)
Code execution errors:
- Review action mode settings
- Use review mode for safety
- Check working directory permissions
- Verify project structure
Performance Issues
Slow Response Times
Diagnosis:
- Enable verbose logging:
--verbose
- Check network latency:
ping api.anthropic.com
- Monitor resource usage:
top
orhtop
- Profile code execution
Solutions:
- Use faster models when available
- Implement response caching
- Optimize prompt length
- Use concurrent requests for multiple queries
Memory Usage
High memory consumption:
- Check for memory leaks in long-running processes
- Use streaming responses when available
- Limit concurrent requests
- Clear response caches periodically
Network and Connectivity
Timeout Errors
ClaifTimeoutError: Request timed out after 120s
Solutions:
- Increase timeout:
claif query "prompt" --timeout 300
- Check network stability
- Use shorter prompts
- Retry with backoff
Proxy Issues
Corporate proxy setup:
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
claif query "test" --provider gemini
SSL Certificate Errors
Solutions:
- Update certificates:
pip install --upgrade certifi
- Use custom CA bundle:
export SSL_CERT_FILE=/path/to/bundle.pem
- Disable SSL verification (not recommended):
export PYTHONHTTPSVERIFY=0
Debugging Strategies
Enable Debug Logging
# Maximum verbosity
export CLAIF_LOG_LEVEL=DEBUG
claif query "test" --verbose
# Component-specific logging
export CLAIF_LOG_FILTER="claif.providers.gemini"
claif query "test" --provider gemini --verbose
Inspect Configuration
# Show current config
claif config show
# Validate configuration
claif config validate
# Test provider connection
claif query "test" --provider claude --dry-run
Analyze Logs
# Save logs to file
claif query "test" --verbose 2> debug.log
# Filter specific issues
grep -i error debug.log
grep -i timeout debug.log
grep -i "provider" debug.log
Getting Help
Before Reporting Issues
- Update to latest version:
uv pip install --upgrade claif
- Check known issues: Review GitHub issues
- Test with minimal example: Isolate the problem
- Gather debug information: Save logs and configuration
Issue Report Template
**Environment:**
- Claif version: `claif --version`
- Python version: `python --version`
- OS: `uname -a`
- Provider packages: `uv pip list | grep claif`
**Problem:**
- Expected behavior:
- Actual behavior:
- Error messages:
**Reproduction:**
- Minimal example:
- Configuration used:
- Debug logs:
Navigation
- Installation Issues - Setup and dependency problems
- Configuration Issues - API keys and settings
- Provider Issues - Provider-specific problems
- Performance - Speed and resource optimization
- Network Issues - Connectivity and proxy problems
- Debugging Guide - Diagnostic tools and techniques