Troubleshooting

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:

Start Docker Desktop
- On macOS/Windows: Launch Docker Desktop from Applications
- On Linux: sudo systemctl start docker
Verify Docker is running
```
docker ps
```
Should show running containers or empty list, not an error.

Check Docker permissions (Linux)

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker ps

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:

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

Stop previous Strix containers

docker ps -a | grep strix
docker stop <container-id>
docker rm <container-id>

Clean up all stopped containers
```
docker container prune -f
```

Container fails to start

Symptom: Container starts then immediately exits Solutions:

Check Docker logs
```
docker logs <container-id>
```
Ensure sufficient resources
- Docker Desktop → Settings → Resources
- Allocate at least 4 GB RAM
- Ensure 10 GB+ free disk space
Pull latest image
```
docker pull usestrix/strix:latest
```

Remove corrupted images

docker images | grep strix
docker rmi <image-id> --force

Image pull fails

Symptom: Cannot download Strix Docker image Solutions:

Check internet connectivity
```
ping docker.io
```
Configure Docker proxy (if behind firewall)
- Docker Desktop → Settings → Resources → Proxies
- Add your proxy configuration

Use alternative registry mirror

export DOCKER_REGISTRY_MIRROR="https://mirror.gcr.io"

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:

Verify API key is correct
```
echo $LLM_API_KEY
```
Should print your key, not empty.

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...

Regenerate API key
- Go to your LLM provider’s dashboard
- Create new API key
- Update environment variable
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:

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"

Check supported models See LLM Providers for complete list.
Verify model access
- Some models require approval or waitlist access
- Check your provider’s dashboard

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:

Wait before retrying
- Most providers: 60 seconds
- Check provider’s rate limit documentation
Use different API key
- Create separate key with independent limits
- Use organization-level keys for higher limits
Upgrade API plan
- Higher tiers usually have increased rate limits
- Consider provider’s team/enterprise plans

Use slower scan mode

export STRIX_REASONING_EFFORT="medium"
strix --target https://app.com --scan-mode quick

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:

Check internet connectivity

ping api.openai.com
ping api.anthropic.com

Increase timeout
```
export LLM_TIMEOUT=600  # 10 minutes
```

Configure proxy if needed

export HTTPS_PROXY="http://proxy.company.com:8080"
export HTTP_PROXY="http://proxy.company.com:8080"

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:

Check account balance
- Log into provider dashboard
- Verify billing information is current
Add credits or upgrade plan
- Add payment method
- Purchase additional credits

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:

Check Python version
```
python --version
python3 --version
```

Install Python 3.12+

# macOS with Homebrew
brew install [email protected]

# Ubuntu/Debian
sudo apt update
sudo apt install python3.12

# Windows: Download from python.org

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:

Upgrade pip
```
pip install --upgrade pip
```

Use pipx (recommended)

# Install pipx
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install Strix with pipx
pipx install strix-agent

Install with verbose output
```
pip install strix-agent -vvv
```
Review errors for specific missing dependencies.

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:

Add pip/pipx to PATH

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc  # or ~/.zshrc

Use python -m

python -m strix --target https://app.com

Verify installation location
```
pip show strix-agent
which strix
```

Scan Issues

Scan hangs or freezes

Symptom: Scan appears stuck with no progress Solutions:

Check LLM API status
- Visit provider status page
- Look for service disruptions

Enable debug logging

export STRIX_LOG_LEVEL=DEBUG
strix --target https://app.com

Reduce scan complexity

strix --target https://app.com --scan-mode quick

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:

Application is secure - This is good news!

Insufficient testing depth

# Use deeper scan mode
strix --target https://app.com --scan-mode deep

Missing authentication

# Provide credentials for authenticated testing
strix --target https://app.com \
  --instruction "Login with username: [email protected], password: test123"

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:

Review findings carefully
- Check the proof-of-concept
- Verify reproduction steps
- Strix validates most findings, but confirm manually

Use higher quality models

# GPT-5 and Claude Sonnet 4.6 have better accuracy
export STRIX_LLM="openai/gpt-5"

Provide more context

strix --target https://app.com \
  --instruction "This is a read-only demo. Ignore CSRF on GET requests."

Report false positives
- Help improve Strix by reporting issues
- GitHub Issues

Scan crashes

Symptom: Strix exits unexpectedly with error Solutions:

Check error message
- Read the full traceback
- Look for specific error codes
Update to latest version
```
pip install --upgrade strix-agent
```
Clear Docker cache
```
docker system prune -a
```
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:

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

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

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:

Verify URL is accessible
```
curl -I https://your-app.com
```

Check for localhost/internal IPs

# Use host.docker.internal for local services
strix --target http://host.docker.internal:3000

Configure Docker network

# For accessing host services
export STRIX_DOCKER_NETWORK="host"

Disable SSL verification (not recommended)
```
export STRIX_VERIFY_SSL=false
```

Only disable SSL verification for testing environments. Never use this for production systems.

Performance Issues

Scans are very slow

Solutions:

Use faster LLM models

# GPT-5 is faster than GPT-4o
export STRIX_LLM="openai/gpt-5"

Enable prompt caching

# Enabled by default, verify it's not disabled
export STRIX_ENABLE_PROMPT_CACHING=true

Use quick scan mode

strix --target https://app.com --scan-mode quick

Allocate more Docker resources
- Docker Desktop → Settings → Resources
- Increase CPU and RAM allocation

High memory usage

Solutions:

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

Getting Help

If you’re still experiencing issues:

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

Community

Security

Troubleshooting

Docker Issues

Docker is not running

Port already in use

Container fails to start

Image pull fails

LLM Connection Issues

Invalid API key

Model not found

Rate limiting

Connection timeout

Quota exceeded

Installation Issues

Python version too old

pip install fails

Command not found

Scan Issues

Scan hangs or freezes

No vulnerabilities found

Too many false positives

Scan crashes

Configuration Issues

Environment variables not persisting

Cannot access target URL

Performance Issues

Scans are very slow

High memory usage

Getting Help

Build docs developers (and LLMs) love

Community

Security

​Docker Issues

​Docker is not running

​Port already in use

​Container fails to start

​Image pull fails

​LLM Connection Issues

​Invalid API key

​Model not found

​Rate limiting

​Connection timeout

​Quota exceeded

​Installation Issues

​Python version too old

​pip install fails

​Command not found

​Scan Issues

​Scan hangs or freezes

​No vulnerabilities found

​Too many false positives

​Scan crashes

​Configuration Issues

​Environment variables not persisting

​Cannot access target URL

​Performance Issues

​Scans are very slow

​High memory usage

​Getting Help

Build docs developers (and LLMs) love

Docker Issues

Docker is not running

Port already in use

Container fails to start

Image pull fails

LLM Connection Issues

Invalid API key

Model not found

Rate limiting

Connection timeout

Quota exceeded

Installation Issues

Python version too old

pip install fails

Command not found

Scan Issues

Scan hangs or freezes

No vulnerabilities found

Too many false positives

Scan crashes

Configuration Issues

Environment variables not persisting

Cannot access target URL

Performance Issues

Scans are very slow

High memory usage

Getting Help