Troubleshooting

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/usestrix/strix/llms.txt

Use this file to discover all available pages before exploring further.

Find solutions to common problems you might encounter when using Strix.

​

Docker Issues

​

Docker is not running

Symptom: Error message “Docker is not available” or “Docker daemon is not running” Solutions:

1. Start Docker Desktop
   • On macOS/Windows: Launch Docker Desktop from Applications
   • On Linux: sudo systemctl start docker
2. Verify Docker is running
   docker ps
   
   Should show running containers or empty list, not an error.
3. Check Docker permissions (Linux)
   # Add your user to docker group
   sudo usermod -aG docker $USER
   
   # Log out and back in, then verify
   docker ps
   
4. Reinstall Docker if necessary
   • Download from docker.com
   • Follow installation instructions for your OS

​

Port already in use

Symptom: Error “port 48080 or 48081 already in use” Solutions:

1. Find and stop the process using the port
   # On macOS/Linux
   lsof -i :48080
   lsof -i :48081
   kill <PID>
   
   # On Windows
   netstat -ano | findstr :48080
   taskkill /PID <PID> /F
   
2. Stop previous Strix containers
   docker ps -a | grep strix
   docker stop <container-id>
   docker rm <container-id>
   
3. Clean up all stopped containers
   docker container prune -f
   

​

Container fails to start

Symptom: Container starts then immediately exits Solutions:

1. Check Docker logs
   docker logs <container-id>
   
2. Ensure sufficient resources
   • Docker Desktop → Settings → Resources
   • Allocate at least 4 GB RAM
   • Ensure 10 GB+ free disk space
3. Pull latest image
   docker pull usestrix/strix:latest
   
4. Remove corrupted images
   docker images | grep strix
   docker rmi <image-id> --force
   

​

Image pull fails

Symptom: Cannot download Strix Docker image Solutions:

1. Check internet connectivity
   ping docker.io
   
2. Configure Docker proxy (if behind firewall)
   • Docker Desktop → Settings → Resources → Proxies
   • Add your proxy configuration
3. Use alternative registry mirror
   export DOCKER_REGISTRY_MIRROR="https://mirror.gcr.io"
   
4. Manual pull with retry
   docker pull usestrix/strix:latest --max-concurrent-downloads 1
   

​

LLM Connection Issues

​

Invalid API key

Symptom: “Authentication failed” or “Invalid API key” Solutions:

1. Verify API key is correct
   echo $LLM_API_KEY
   
   Should print your key, not empty.
2. Check for extra spaces or quotes
   # Correct
   export LLM_API_KEY="sk-proj-abc123..."
   
   # Incorrect (no quotes needed if no spaces)
   export LLM_API_KEY=sk-proj-abc123...
   
3. Regenerate API key
   • Go to your LLM provider’s dashboard
   • Create new API key
   • Update environment variable
4. Check key permissions
   • Ensure API key has necessary permissions
   • Some providers require specific scopes enabled

​

Model not found

Symptom: “Model ‘X’ not found” or “Unsupported model” Solutions:

1. Use correct model format
   # Correct formats
   export STRIX_LLM="openai/gpt-5"
   export STRIX_LLM="anthropic/claude-sonnet-4-6"
   export STRIX_LLM="vertex_ai/gemini-3-pro-preview"
   
2. Check supported models See LLM Providers for complete list.
3. Verify model access
   • Some models require approval or waitlist access
   • Check your provider’s dashboard
4. Use alternative model
   # If GPT-5 unavailable, try GPT-4o
   export STRIX_LLM="openai/gpt-4o"
   

​

Rate limiting

Symptom: “Rate limit exceeded” or 429 errors Solutions:

1. Wait before retrying
   • Most providers: 60 seconds
   • Check provider’s rate limit documentation
2. Use different API key
   • Create separate key with independent limits
   • Use organization-level keys for higher limits
3. Upgrade API plan
   • Higher tiers usually have increased rate limits
   • Consider provider’s team/enterprise plans
4. Use slower scan mode
   export STRIX_REASONING_EFFORT="medium"
   strix --target https://app.com --scan-mode quick
   
5. Switch to different provider
   # Use Anthropic instead of OpenAI
   export STRIX_LLM="anthropic/claude-sonnet-4-6"
   export LLM_API_KEY="sk-ant-..."
   

​

Connection timeout

Symptom: “Connection timeout” or “Request timed out” Solutions:

1. Check internet connectivity
   ping api.openai.com
   ping api.anthropic.com
   
2. Increase timeout
   export LLM_TIMEOUT=600  # 10 minutes
   
3. Configure proxy if needed
   export HTTPS_PROXY="http://proxy.company.com:8080"
   export HTTP_PROXY="http://proxy.company.com:8080"
   
4. Use different API base URL
   # For Azure OpenAI
   export LLM_API_BASE="https://your-resource.openai.azure.com"
   

​

Quota exceeded

Symptom: “Quota exceeded” or “Insufficient credits” Solutions:

1. Check account balance
   • Log into provider dashboard
   • Verify billing information is current
2. Add credits or upgrade plan
   • Add payment method
   • Purchase additional credits
3. Use Strix Router for free credit
   # Get $10 free at https://models.strix.ai
   export STRIX_LLM="strix/gpt-5"
   export LLM_API_KEY="your-strix-router-key"
   

​

Installation Issues

​

Python version too old

Symptom: “Python 3.12+ required” or import errors Solutions:

1. Check Python version
   python --version
   python3 --version
   
2. Install Python 3.12+
   # macOS with Homebrew
   brew install python@3.12
   
   # Ubuntu/Debian
   sudo apt update
   sudo apt install python3.12
   
   # Windows: Download from python.org
   
3. Use pyenv for version management
   # Install pyenv
   curl https://pyenv.run | bash
   
   # Install Python 3.12
   pyenv install 3.12.0
   pyenv global 3.12.0
   

​

pip install fails

Symptom: Errors during pip install strix-agent Solutions:

1. Upgrade pip
   pip install --upgrade pip
   
2. Use pipx (recommended)
   # Install pipx
   python3 -m pip install --user pipx
   python3 -m pipx ensurepath
   
   # Install Strix with pipx
   pipx install strix-agent
   
3. Install with verbose output
   pip install strix-agent -vvv
   
   Review errors for specific missing dependencies.
4. Install from source
   git clone https://github.com/usestrix/strix.git
   cd strix
   poetry install
   

​

Command not found

Symptom: strix: command not found after installation Solutions:

1. Add pip/pipx to PATH
   # Add to ~/.bashrc or ~/.zshrc
   export PATH="$HOME/.local/bin:$PATH"
   
   # Reload shell
   source ~/.bashrc  # or ~/.zshrc
   
2. Use python -m
   python -m strix --target https://app.com
   
3. Verify installation location
   pip show strix-agent
   which strix
   

​

Scan Issues

​

Scan hangs or freezes

Symptom: Scan appears stuck with no progress Solutions:

1. Check LLM API status
   • Visit provider status page
   • Look for service disruptions
2. Enable debug logging
   export STRIX_LOG_LEVEL=DEBUG
   strix --target https://app.com
   
3. Reduce scan complexity
   strix --target https://app.com --scan-mode quick
   
4. Check system resources
   # Monitor CPU and memory
   htop  # or top
   
   # Check Docker resource usage
   docker stats
   

​

No vulnerabilities found

Symptom: Scan completes but reports no findings Possible causes:

1. Application is secure - This is good news!
2. Insufficient testing depth
   # Use deeper scan mode
   strix --target https://app.com --scan-mode deep
   
3. Missing authentication
   # Provide credentials for authenticated testing
   strix --target https://app.com \
     --instruction "Login with username: test@example.com, password: test123"
   
4. Scope too narrow
   # Remove restrictive instructions
   strix --target https://app.com
   # Instead of: --instruction "Only test /api endpoint"
   

​

Too many false positives

Symptom: Scan reports vulnerabilities that don’t exist Solutions:

1. Review findings carefully
   • Check the proof-of-concept
   • Verify reproduction steps
   • Strix validates most findings, but confirm manually
2. Use higher quality models
   # GPT-5 and Claude Sonnet 4.6 have better accuracy
   export STRIX_LLM="openai/gpt-5"
   
3. Provide more context
   strix --target https://app.com \
     --instruction "This is a read-only demo. Ignore CSRF on GET requests."
   
4. Report false positives
   • Help improve Strix by reporting issues
   • GitHub Issues

​

Scan crashes

Symptom: Strix exits unexpectedly with error Solutions:

1. Check error message
   • Read the full traceback
   • Look for specific error codes
2. Update to latest version
   pip install --upgrade strix-agent
   
3. Clear Docker cache
   docker system prune -a
   
4. Report the crash
   • Include full error traceback
   • GitHub Issues

​

Configuration Issues

​

Environment variables not persisting

Symptom: Variables work in terminal but not after restart Solutions:

1. Add to shell configuration
   # For bash: ~/.bashrc
   # For zsh: ~/.zshrc
   export STRIX_LLM="openai/gpt-5"
   export LLM_API_KEY="your-api-key"
   
   # Reload
   source ~/.bashrc  # or ~/.zshrc
   
2. Use Strix config file Strix saves configuration to ~/.strix/cli-config.json automatically.
   # First run saves config
   strix --target https://app.com
   
   # Subsequent runs use saved config
   strix --target https://other-app.com
   
3. Use .env file
   # Create .env in project directory
   echo 'STRIX_LLM="openai/gpt-5"' > .env
   echo 'LLM_API_KEY="your-key"' >> .env
   
   # Load before running
   source .env && strix --target https://app.com
   

​

Cannot access target URL

Symptom: “Cannot connect to target” or “Target unreachable” Solutions:

1. Verify URL is accessible
   curl -I https://your-app.com
   
2. Check for localhost/internal IPs
   # Use host.docker.internal for local services
   strix --target http://host.docker.internal:3000
   
3. Configure Docker network
   # For accessing host services
   export STRIX_DOCKER_NETWORK="host"
   
4. Disable SSL verification (not recommended)
   export STRIX_VERIFY_SSL=false
   

​

Performance Issues

​

Scans are very slow

Solutions:

1. Use faster LLM models
   # GPT-5 is faster than GPT-4o
   export STRIX_LLM="openai/gpt-5"
   
2. Enable prompt caching
   # Enabled by default, verify it's not disabled
   export STRIX_ENABLE_PROMPT_CACHING=true
   
3. Use quick scan mode
   strix --target https://app.com --scan-mode quick
   
4. Allocate more Docker resources
   • Docker Desktop → Settings → Resources
   • Increase CPU and RAM allocation

​

High memory usage

Solutions:

1. Limit concurrent agents
   export STRIX_MAX_AGENTS=3
   
2. Use smaller context windows
   export STRIX_MAX_CONTEXT=50000
   
3. Close other applications
   • Free up system RAM
   • Docker requires significant resources

​

Getting Help

If you’re still experiencing issues:

1. Search existing issues
   • GitHub Issues
   • Someone may have encountered the same problem
2. Join Discord community
   • discord.gg/strix-ai
   • Get real-time help from community
3. Create detailed bug report
   • Include system information
   • Provide full error traceback
   • List steps to reproduce
   • See Contributing Guide
4. Check documentation
   • Installation Guide
   • Configuration Reference
   • LLM Providers