Skip to main content

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​

  1. Check existing issues: Search GitHub issues
  2. Provide details: Include config, command, error output
  3. Minimal reproduction: Create small test case
  4. Environment info: Python version, OS, Upsilon version
# Generate debug info
upsilon --version
python --version
pip list | grep -E "(upsilon|anthropic|pydantic)"