If you encounter issues with SpiderFoot, use this guide to diagnose and resolve common problems. For additional help, consult the documentation, GitHub Issues, or the Discord community.

• Check logs: Review logs in the logs/ directory for error messages and stack traces.
• Verify dependencies: Ensure all required Python packages are installed. Use pip install -r requirements.txt to install missing dependencies.
• Restart the application: Sometimes, simply restarting SpiderFoot or your Docker container resolves transient issues.
• Check for updates: Make sure you are running the latest version of SpiderFoot and its dependencies.

Below is a simple troubleshooting workflow for SpiderFoot. Follow the arrows to diagnose and resolve issues efficiently.

flowchart TD
    A[SpiderFoot Issue Detected] --> B{Is there an error in logs?}
    B -- Yes --> C[Read error message]
    C --> D{Is it a dependency error?}
    D -- Yes --> E[Run pip install -r requirements.txt]
    D -- No --> F{Is it a config error?}
    F -- Yes --> G[Check config file syntax and permissions]
    F -- No --> H[Search error message online or in docs]
    B -- No --> I[Check Docker/container logs]
    I --> J{Is it a Docker issue?}
    J -- Yes --> K[Check volume permissions, ports, and restart container]
    J -- No --> L[Ask for help on GitHub or Discord]
    H --> L
    G --> M[Restart SpiderFoot]
    E --> M
    K --> M
    M --> N[Issue resolved?]
    N -- Yes --> O[Done]
    N -- No --> L

flowchart LR
    A[Problem Detected] --> B{Web UI or CLI?}
    B -- Web UI --> C{Page Loads?}
    C -- No --> D[Check server status and port]
    C -- Yes --> E{Scan Results Appear?}
    E -- No --> F[Check logs, API keys, modules]
    E -- Yes --> G[Check for data completeness]
    B -- CLI --> H{Error Message?}
    H -- Yes --> I[Read and search error]
    H -- No --> J[Check command syntax]

flowchart TD
    A[Docker Container Fails] --> B{Check logs}
    B -- Error found --> C[Resolve error]
    B -- No error --> D[Check volume mounts]
    D --> E{Permissions OK?}
    E -- No --> F[Fix permissions]
    E -- Yes --> G[Check network settings]
    G --> H{Ports open?}
    H -- No --> I[Open required ports]
    H -- Yes --> J[Ask for help]

flowchart TD
    A[API Call Fails] --> B{Error Message?}
    B -- 401/403 --> C[Check API key/auth]
    B -- 404 --> D[Check endpoint URL]
    B -- 500 --> E[Check server logs]
    B -- CORS --> F[Check browser/network]
    B -- Other --> G[Search docs/community]

flowchart TD
    A[Error Occurs] --> B{Type?}
    B -- Dependency --> C[Install/Update Python packages]
    B -- Config --> D[Check config file, env vars]
    B -- Network --> E[Check ports, firewall, DNS]
    B -- API --> F[Check API keys, endpoint, docs]
    B -- Docker --> G[Check logs, volumes, permissions]
    B -- Unknown --> H[Search docs/community]

flowchart TD
    A[Need Help?] --> B[Check Documentation]
    B --> C[Search GitHub Issues]
    C --> D[Ask on Discord]
    D --> E[Contact Maintainer]

If you can't resolve your issue, visit the GitHub Issues page or join the Discord community for support. Please provide detailed information about your environment and the problem (OS, Python version, Docker version, error messages, steps to reproduce, etc.).

• Official Documentation
• User Guide
• API Reference
• Modules Index
• Developer Guide
• Advanced Topics

A full, detailed description for each module is available in the documentation/modules/ folder. Each file describes the module's purpose, usage, required API keys, and example output.

SpiderFoot v6.0.0 includes enhanced modules that may require specific troubleshooting approaches:

• Rate Limiting: TikTok has strict rate limits; adjust delay settings in module configuration
• User Agent Blocking: Enable user agent rotation in configuration
• Profile Access: Some profiles may be private or restricted; module will skip these gracefully
• API Changes: TikTok frequently updates their interface; check for module updates

• API Key Errors: Verify BlockCypher and Etherscan API keys are valid and have sufficient quota
• Network Timeouts: Blockchain APIs can be slow; increase timeout settings
• Invalid Addresses: Ensure cryptocurrency addresses are properly formatted
• Rate Limiting: Blockchain APIs have strict limits; use built-in rate limiting features

• High Memory Usage: Large datasets can consume significant memory; adjust max_entities setting
• Slow Processing: Complex correlations take time; consider increasing confidence thresholds
• False Positives: Adjust similarity thresholds to reduce false correlations
• Database Performance: Large correlation graphs may slow database queries

• Cache Not Working: Verify cache configuration and permissions for cache directory
• Memory Leaks: Monitor memory usage and adjust garbage collection settings
• Rate Limit Conflicts: Ensure rate limiting doesn't conflict with other modules
• Performance Degradation: Check cache hit rates and optimize cache size/TTL settings

• API Key Problems: Verify OpenAI API key is valid and has sufficient credits
• High Costs: Monitor token usage and enable cost optimization features
• Poor Summaries: Adjust model temperature and prompt engineering settings
• Rate Limiting: OpenAI has rate limits; configure appropriate delays

Authored by poppopjmp