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.