Troubleshooting
Common issues and solutions when using Upsilon.
Installation Issues
ImportError: No module named 'upsilon'
Problem: Upsilon is not installed or not in Python path.
Solutions:
# Check Python environment
python -c "import sys; print(sys.path)"
# Install/reinstall Upsilon
pip install --upgrade upsilon
# For development installation
pip install -e .
# Check installation
python -c "import upsilon; print(upsilon.__version__)"
Command not found: upsilon
Problem: Upsilon CLI is not in system PATH.
Solutions:
# Check if installed in user directory
python -m upsilon --help
# Add to PATH (Linux/Mac)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# For rye installations
rye run upsilon --help
Configuration Issues
Config file not found
Problem: Upsilon can't find pyproject.toml.
Solutions:
# Check current directory
pwd
ls -la pyproject.toml
# Specify config explicitly
upsilon review --config=path/to/pyproject.toml file.py
# Create minimal config
echo '[tool.upsilon]
model = "claude-3-haiku-20240307"' > pyproject.toml
Invalid configuration
Problem: Configuration validation errors.
Common fixes:
# Fix: Invalid model name
[tool.upsilon]
model = "claude-3-haiku-20240307" # Correct format
# Fix: Invalid temperature
temperature = 0.1 # Must be between 0.0 and 2.0
# Fix: Invalid tool configuration
[tool.upsilon.builtin-tools]
spell_check = { enabled = true } # Must be a table
Configuration not loading
Problem: Changes to config not taking effect.
Debug steps:
# Check config loading
upsilon config-info
# Verify config syntax
python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb')))"
# Clear cache (if using)
rm -rf ~/.cache/upsilon/
API and Authentication Issues
Invalid API key
Problem: ANTHROPIC_API_KEY is invalid or missing.
Solutions:
# Check API key is set
echo $ANTHROPIC_API_KEY
# Set API key
export ANTHROPIC_API_KEY="your-key-here"
# Test with mock mode first
upsilon review --mock file.py
# Validate API key format (should start with 'sk-')
Rate limiting
Problem: API calls being rate limited.
Solutions:
# Use mock mode for development
upsilon review --mock file.py
# Reduce token limits
[tool.upsilon]
max_tokens = 1000
# Add delays between files
# (handled automatically by Upsilon)
Network connectivity
Problem: Can't connect to Anthropic API.
Debug steps:
# Test connectivity
curl -I https://api.anthropic.com
# Check proxy settings
echo $HTTP_PROXY $HTTPS_PROXY
# Use mock mode as fallback
upsilon review --mock file.py
Tool Detection Issues
External tool not found
Problem: mypy, ruff, or other tools not detected.
Solutions:
# Check tool installation
which mypy
which ruff
# Install missing tools
pip install mypy ruff
# Check Python module availability
python -m mypy --version
python -m ruff --version
# Verify tool detection
upsilon list-tools
Tool execution timeout
Problem: External tools taking too long.
Solutions:
# Increase timeout
[tool.upsilon.external-tools.mypy]
timeout = 120 # 2 minutes
# Or disable slow tools
[tool.upsilon.rules]
check_security = false # Disables external tools
Tool permission errors
Problem: External tools can't execute.
Solutions:
# Check permissions
ls -la $(which mypy)
# Fix permissions
chmod +x $(which mypy)
# Check if tool is corrupted
pip reinstall mypy
Performance Issues
Slow review times
Problem: Reviews taking too long.
Optimizations:
# Use faster model
[tool.upsilon]
model = "claude-3-haiku-20240307"
# Reduce token limits
max_tokens = 1000
# Disable expensive tools
[tool.upsilon.builtin-tools]
import_analysis = { enabled = false }
# Limit file types
ignore_patterns = [
"*.min.js",
"*.bundle.js",
"node_modules/*",
"build/*"
]
Memory usage
Problem: High memory consumption.
Solutions:
# Review files individually
for file in src/*.py; do
upsilon review "$file"
done
# Use smaller batch sizes
upsilon review file1.py file2.py # Instead of src/*
# Monitor memory usage
time upsilon review src/
Temporary file issues
Problem: Temporary files not cleaned up.
Solutions:
# Clean temporary files manually
rm -rf /tmp/upsilon_*
# Check disk space
df -h /tmp
# Ensure proper cleanup in config
[tool.upsilon]
cleanup_temp_files = true
File Processing Issues
Unsupported file type
Problem: File type not recognized.
Solutions:
# Check supported extensions
upsilon list-tools
# Force language detection
upsilon review --language=python file.txt
# Add custom file extensions
[tool.upsilon.languages.python]
extensions = [".py", ".pyi", ".pyx"]
Encoding issues
Problem: Can't read file due to encoding.
Solutions:
# Check file encoding
file -i problematic_file.py
# Convert encoding
iconv -f iso-8859-1 -t utf-8 file.py > file_utf8.py
# Skip problematic files
[tool.upsilon]
ignore_patterns = ["*problematic_file*"]
Large file handling
Problem: Files too large to process.
Solutions:
# Increase token limits
[tool.upsilon]
max_tokens = 4000
# Or exclude large files
ignore_patterns = ["*large_file.py"]
Output and Formatting Issues
No output displayed
Problem: Upsilon runs but shows no output.
Debug steps:
# Use verbose mode
upsilon review --verbose file.py
# Check for errors
upsilon review file.py 2>&1 | tee output.log
# Try different format
upsilon review --format=json file.py
JSON parsing errors
Problem: Can't parse JSON output.
Solutions:
# Validate JSON output
upsilon review --format=json file.py | jq .
# Use text format instead
upsilon review --format=text file.py
# Check for mixed output
upsilon review --quiet --format=json file.py
Integration Issues
Pre-commit hook failing
Problem: Upsilon hook fails in pre-commit.
Debug steps:
# Test hook manually
pre-commit run upsilon --files file.py
# Check hook configuration
cat .pre-commit-config.yaml
# Update hooks
pre-commit autoupdate
# Run with verbose output
pre-commit run --verbose upsilon
CI/CD failures
Problem: Upsilon fails in CI environment.
Common fixes:
# GitHub Actions example
- name: Install dependencies
run: |
pip install upsilon
# Install external tools
pip install mypy ruff
- name: Run Upsilon
run: upsilon review src/ --mock # Use mock in CI
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
Debugging Techniques
Enable debug logging
# Set debug environment variable
export UPSILON_DEBUG=1
upsilon review file.py
# Or use Python logging
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from upsilon.main import app
app()
"
Isolate issues
# Test with minimal config
echo '[tool.upsilon]
model = "claude-3-haiku-20240307"' > minimal.toml
upsilon review --config=minimal.toml --mock file.py
# Test individual tools
python -c "
from upsilon.tools.builtin import SpellChecker
checker = SpellChecker('spell_check', {})
result = checker.analyze('test content', 'test.py', 'python')
print(result)
"
Get help
# Check version
upsilon --version
# Get help
upsilon --help
upsilon review --help
# Show configuration
upsilon config-info
# List available tools
upsilon list-tools
Common Error Messages
"No tools available"
Cause: No analysis tools are enabled or available.
Fix:
[tool.upsilon.builtin-tools]
spell_check = { enabled = true }
syntax_check = { enabled = true }
"File not found"
Cause: Specified file doesn't exist.
Fix: Check file path and permissions.
"Language not supported"
Cause: File extension not recognized.
Fix: Add to supported languages or specify explicitly.
"API request failed"
Cause: Issue with Anthropic API call.
Fix: Check API key, network, use mock mode.
Getting Support
- Check existing issues: Search GitHub issues
- Provide details: Include config, command, error output
- Minimal reproduction: Create small test case
- Environment info: Python version, OS, Upsilon version
# Generate debug info
upsilon --version
python --version
pip list | grep -E "(upsilon|anthropic|pydantic)"