Skip to main content

Troubleshooting FuzzForge

Running into issues with FuzzForge? This guide will help you diagnose and resolve the most common problems—whether you’re just getting started or running complex workflows. Each section is focused on a specific area, with actionable steps and explanations.

Quick Checks: Is Everything Running?​

Before diving into specific errors, let’s check the basics:

# Check all FuzzForge services
docker compose -f docker-compose.yml ps

# Test service health endpoints
curl http://localhost:8000/health
curl http://localhost:8080  # Temporal Web UI
curl http://localhost:9000  # MinIO API
curl http://localhost:9001  # MinIO Console

If any of these commands fail, note the error message and continue below.

Environment Configuration Issues​

Docker Compose fails with "file not found" or variable errors​

What's happening? The required volumes/env/.env file is missing. Docker Compose needs this file to start.

How to fix:

# Create the environment file from the template
cp volumes/env/.env.template volumes/env/.env

# Restart Docker Compose
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml up -d

Note: You can leave the .env file with default values if you're only using basic workflows (no AI features).

API key errors for AI features​

What's happening? AI-powered workflows (like llm_secret_detection) or the AI agent need API keys.

How to fix:

  1. Edit volumes/env/.env and add your keys:

    LITELLM_MODEL=gpt-4o-mini
    OPENAI_API_KEY=sk-your-key-here

  2. Restart the backend to pick up new environment variables:

    docker compose restart backend

Which workflows need API keys?

  • ✅ Don't need keys: security_assessment, gitleaks_detection, trufflehog_detection, atheris_fuzzing, cargo_fuzzing
  • ⚠️ Need keys: llm_secret_detection, AI agent (fuzzforge ai agent)

Workflow Execution Issues​

Upload fails or file access errors​

What's happening? File upload to MinIO failed or worker can't download target.

How to fix:

  • Check MinIO is running: 
    docker-compose -f docker-compose.yml ps minio
  • Check MinIO logs: 
    docker-compose -f docker-compose.yml logs minio
  • Verify MinIO is accessible: 
    curl http://localhost:9000
  • Check file size (max 10GB by default).

Workflow status is "Failed" or "Running" (stuck)​

What's happening?

  • "Failed": Usually a target download, storage, or tool error.
  • "Running" (stuck): Worker is overloaded, target download failed, or worker crashed.

How to fix:

  • Check worker logs for details: 
    docker-compose -f docker-compose.yml logs worker-rust | tail -50
  • Check Temporal Web UI at http://localhost:8080 for detailed execution history
  • Restart services: 
    docker-compose -f docker-compose.yml down
    docker-compose -f docker-compose.yml up -d
  • Reduce the number of concurrent workflows if your system is resource-constrained.

Workflow requires worker not running​

What's happening? You see a warning message like:

⚠️  Could not check worker requirements: Cannot find docker-compose.yml.
   Ensure backend is running, run from FuzzForge directory, or set
   FUZZFORGE_ROOT environment variable.
   Continuing without worker management...

Or the workflow fails to start because the required worker isn't running.

How to fix: Start the worker required for your workflow before running it:

WorkflowWorker RequiredStartup Command
android_static_analysisworker-androiddocker compose up -d worker-android
security_assessmentworker-pythondocker compose up -d worker-python
python_sastworker-pythondocker compose up -d worker-python
llm_analysisworker-pythondocker compose up -d worker-python
atheris_fuzzingworker-pythondocker compose up -d worker-python
ossfuzz_campaignworker-ossfuzzdocker compose up -d worker-ossfuzz
cargo_fuzzingworker-rustdocker compose up -d worker-rust
llm_secret_detectionworker-secretsdocker compose up -d worker-secrets
trufflehog_detectionworker-secretsdocker compose up -d worker-secrets
gitleaks_detectionworker-secretsdocker compose up -d worker-secrets

Check worker status:

# Check if a specific worker is running
docker compose ps worker-android

# Check all workers
docker compose ps | grep worker

Note: Workers don't auto-start by default to save system resources. For more details on worker management, see the Docker Setup guide.

Service Connectivity Issues​

Backend (port 8000) or Temporal UI (port 8233) not responding​

How to fix:

  • Check if the service is running: 
    docker-compose -f docker-compose.yml ps fuzzforge-backend
    docker-compose -f docker-compose.yml ps temporal
  • View logs for errors: 
    docker-compose -f docker-compose.yml logs fuzzforge-backend --tail 50
    docker-compose -f docker-compose.yml logs temporal --tail 20
  • Restart the affected service: 
    docker-compose -f docker-compose.yml restart fuzzforge-backend
    docker-compose -f docker-compose.yml restart temporal

CLI Issues​

"fuzzforge: command not found"​

How to fix:

  • Install the CLI: 
    cd cli
    pip install -e .
    or 
    uv tool install .
  • Check your PATH: 
    which fuzzforge
    echo $PATH
  • As a fallback: 
    python -m fuzzforge_cli --help

CLI connection errors​

How to fix:

  • Make sure the backend is running and healthy.
  • Check your CLI config: 
    fuzzforge config show
  • Update the server URL if needed: 
    fuzzforge config set-server http://localhost:8000

System Resource Issues​

Out of disk space​

How to fix:

  • Clean up Docker: 
    docker system prune -f
    docker image prune -f
    docker volume prune -f  # Remove unused volumes
  • Clean worker cache manually if needed: 
    docker exec fuzzforge-worker-python rm -rf /cache/*
    docker exec fuzzforge-worker-rust rm -rf /cache/*

High memory usage​

How to fix:

  • Limit the number of concurrent workflows.
  • Add swap space if possible.
  • Restart services to free up memory.

Network Issues​

Services can’t communicate​

How to fix:

  • Check Docker network configuration: 
    docker network ls
    docker network inspect fuzzforge-temporal_default
  • Recreate the network: 
    docker-compose -f docker-compose.yml down
    docker network prune -f
    docker-compose -f docker-compose.yml up -d

Workflow-Specific Issues​

Static analysis or secret detection finds no issues​

What’s happening?

  • Your code may be clean, or the workflow isn’t scanning the right files.

How to fix:

  • Make sure your target contains files to analyze: 
    find /path/to/target -name "*.py" -o -name "*.js" -o -name "*.java" | head -10
  • Test with a known-vulnerable project or file.

Getting Help and Diagnostics​

Enable debug logging​

export TEMPORAL_LOGGING_LEVEL=DEBUG
docker-compose -f docker-compose.yml down
docker-compose -f docker-compose.yml up -d
docker-compose -f docker-compose.yml logs fuzzforge-backend -f

Collect diagnostic info​

Save and run this script to gather info for support:

#!/bin/bash
echo "=== FuzzForge Diagnostics ==="
date
docker compose -f docker-compose.yml ps
curl -s http://localhost:8000/health || echo "Backend unhealthy"
curl -s http://localhost:8080 >/dev/null && echo "Temporal UI healthy" || echo "Temporal UI unhealthy"
curl -s http://localhost:9000 >/dev/null && echo "MinIO healthy" || echo "MinIO unhealthy"
docker compose -f docker-compose.yml logs --tail 10

Still stuck?​

  • Check the FAQ (not yet available)
  • Review the Getting Started guide
  • Submit an issue with your diagnostics output
  • Join the community or check for similar issues

Prevention & Maintenance Tips​

  • Regularly clean up Docker images and containers: 
    docker system prune -f
  • Monitor disk space and memory usage.
  • Back up your configuration files (docker-compose.yaml, .env, daemon.json).
  • Add health checks to your monitoring scripts.

If you have a persistent or unusual issue, don’t hesitate to reach out with logs and details. FuzzForge is designed to be robust, but every environment is unique—and your feedback helps make it better!