Troubleshooting

This guide covers common issues you might encounter when using Fraim and their solutions.

Installation Issues

Python Version Compatibility

Problem: Fraim fails to install or run due to Python version issues.

Solution:

# Check your Python version
python --version

# Ensure you have Python 3.10 or higher
python3.12 --version

# If using the wrong version, specify the correct Python
python3.12 -m pip install uv

uv Installation Problems

Problem: uv command not found after installation.

Solution:

# Add uv to your PATH (Linux/macOS)
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh users
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Alternative: Install via pip
pip install uv

Permission Errors

Problem: Permission denied when installing or running Fraim.

Solution:

# Fix ownership of uv directories (Linux/macOS)
sudo chown -R $USER:$USER ~/.local/share/uv

# Use user installation mode
uv sync --user

# On Windows, run as Administrator or check UAC settings

Configuration Issues

API Key Problems

Problem: “API key not found” or authentication errors.

Solutions:

1. Check Environment Variables:

   echo $GEMINI_API_KEY
   echo $OPENAI_API_KEY
   echo $ANTHROPIC_API_KEY
   

2. Verify .env File:

   cat .env
   # Should contain: GEMINI_API_KEY=your_key_here
   

3. Test API Connectivity:

   # Test with a small analysis
   fraim --debug code --location . --limit 1
   

Model Configuration Issues

Problem: “Model not supported” or incorrect model names.

Solution:

# Use correct model format
fraim --model gemini/gemini-2.5-flash code --location .  # ✅ Correct
fraim --model gemini-flash code --location .             # ❌ Incorrect

# Available models:
fraim --model gemini/gemini-2.5-flash code --location .
fraim --model gpt-4 code --location .
fraim --model gpt-3.5-turbo code --location .
fraim --model claude-3-sonnet-20240229 code --location .

Runtime Issues

Memory Problems

Problem: Out of memory errors or system freezing during analysis.

Solutions:

1. Reduce Chunk Size:

   fraim code --location . --chunk-size 200
   

2. Limit File Analysis:

   fraim code --location . --limit 50
   

3. Monitor System Resources:

   # Check memory usage during analysis
   top
   htop  # If available
   

Performance Issues

Problem: Analysis is very slow or hangs.

Solutions:

1. Optimize Chunk Size:

   # Smaller chunks for detailed analysis
   fraim code --location . --chunk-size 300
   
   # Larger chunks for faster processing
   fraim code --location . --chunk-size 800
   

2. Use File Limits:

   # Test with fewer files first
   fraim --debug code --location . --limit 20
   

3. Check Network Connectivity:

   # Test API response time
   ping api.openai.com
   curl -I https://generativelanguage.googleapis.com
   

API Rate Limiting

Problem: “Too many requests” or rate limit errors.

Solutions:

1. Increase Chunk Size:

   fraim code --location . --chunk-size 1000
   

2. Use Different Model:

   # Some models have higher rate limits
   fraim --model gpt-3.5-turbo code --location .
   

3. Check API Quotas:

   • Review your API provider’s usage dashboard
   • Upgrade your API plan if needed

Analysis Issues

No Files Found

Problem: Fraim reports “No files found” or analyzes fewer files than expected.

Solutions:

1. Check File Patterns:

   # Verify files exist
   find . -name "*.py" | head -10
   
   # Test with specific patterns
   fraim --debug code --location . --globs "*.py"
   

2. Debug File Discovery:

   fraim --debug code --location . | grep -i "found"
   

3. Check Directory Permissions:

   ls -la /path/to/your/project
   

Poor Quality Results

Problem: Too many false positives or missing real vulnerabilities.

Solutions:

1. Adjust Confidence Threshold:

   # Fewer false positives
   fraim --confidence 8 code --location .
   
   # More comprehensive analysis
   fraim --confidence 5 code --location .
   

2. Optimize Chunk Size:

   # Better context for analysis
   fraim code --location . --chunk-size 300
   

3. Use Better Model:

   # More capable models
   fraim --model gpt-4 code --location .
   fraim --model claude-3-opus-20240229 code --location .
   

Incomplete Analysis

Problem: Analysis stops early or doesn’t process all files.

Solutions:

1. Check Debug Output:

   fraim --debug code --location . | tail -50
   

2. Verify Disk Space:

   df -h
   

3. Check File Size Limits:

   # Skip very large files
   find . -name "*.py" -size +1M
   

Output Issues

Missing Reports

Problem: SARIF or HTML reports are not generated.

Solutions:

1. Check Output Directory:

   ls -la fraim_output/
   

2. Verify Permissions:

   # Check write permissions
   touch fraim_output/test.txt
   rm fraim_output/test.txt
   

3. Use Custom Output Path:

   fraim --output /tmp/fraim-reports/ code --location .
   

Corrupted Reports

Problem: Reports are empty or malformed.

Solutions:

1. Check for Errors:

   fraim --debug code --location . | grep -i error
   

2. Verify Analysis Completed:

   # Look for completion messages
   fraim --debug code --location . | grep -i "completed"
   

3. Test with Minimal Example:

   mkdir test-fraim
   echo "print('hello')" > test-fraim/test.py
   fraim code --location test-fraim --limit 1
   

Integration Issues

CI/CD Pipeline Failures

Problem: Fraim fails in automated environments.

Solutions:

1. Check Environment Variables:

   # GitHub Actions example
   env:
     GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
   

2. Use Non-Interactive Mode:

   # Avoid hanging in CI
   fraim --confidence 8 code --location . --chunk-size 500
   

3. Set Timeouts:

   # Prevent infinite hangs
   timeout 30m fraim code --location .
   

Docker Issues

Problem: Running Fraim in containers.

Solutions:

1. Dockerfile Example:

   FROM python:3.12-slim
   
   RUN pip install uv
   COPY . /app
   WORKDIR /app
   RUN uv sync
   
   # Set environment variables
   ENV GEMINI_API_KEY=${GEMINI_API_KEY}
   
   CMD ["uv", "run", "fraim", "code", "--location", "."]
   

2. Memory Limits:

   docker run --memory=4g fraim-image
   

Debugging Techniques

Enable Debug Logging

# Full debug output
fraim --debug code --location .

# Filter for specific issues
fraim --debug code --location . | grep -i "error\|warning\|failed"

# Save debug output
fraim --debug code --location . > debug.log 2>&1

Test Minimal Examples

# Create test directory
mkdir fraim-test
cd fraim-test

# Add simple vulnerable code
cat > vulnerable.py << 'EOF'
import os
password = "hardcoded123"
user_input = input("Enter command: ")
os.system(user_input)
EOF

# Test analysis
fraim --debug code --location . --limit 1

System Information

# Gather system info for bug reports
echo "Python: $(python --version)"
echo "uv: $(uv --version)"
echo "OS: $(uname -a)"
echo "Memory: $(free -h 2>/dev/null || vm_stat)"
echo "Disk: $(df -h .)"

Getting Help

Before Reporting Issues

1. Update Fraim:

   cd fraim
   git pull origin main
   uv sync
   

2. Clear Cache:

   rm -rf ~/.cache/uv/
   uv sync
   

3. Test Minimal Example:

   • Create a small test case that reproduces the issue
   • Include debug output

Reporting Bugs

When reporting issues, include:

1. System Information:

   • Operating system and version
   • Python version
   • uv version
   • Fraim version/commit

2. Command Used:

   fraim --debug code --location .
   

3. Debug Output:

   • Full debug log (use --debug)
   • Error messages
   • Stack traces

4. Expected vs Actual Behavior:

   • What you expected to happen
   • What actually happened

Community Support

• GitHub Issues: Create an issue
• Discussions: Join community discussions for questions
• Documentation: Check other documentation sections

---

Still having issues? Check the Configuration Guide for advanced setup options or create an issue with your debug output.