# Troubleshooting Guide

Solutions for common issues encountered when installing, configuring, and operating the Donjon Platform.

## Common Installation Issues

Python not found

Symptom: The launcher displays "ERROR: Python 3 not found".

Cause: Python 3.10+ is not installed or not on the system PATH.

Solution:

1. Download Python 3.10+ from python.org
2. During installation, check "Add Python to PATH"
3. Restart your terminal after installation
4. Verify: `python --version` or `python3 --version`

On Windows, also try the Python launcher: `py -3 --version`

Execution policy error (PowerShell)

Symptom: `donjon-launcher.ps1 cannot be loaded because running scripts is disabled on this system`

Solution: Run one of these commands:

    # Option 1: Set policy for current user (recommended)
    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

    # Option 2: Bypass for this session only
    powershell -ExecutionPolicy Bypass -File bin\donjon-launcher.ps1

    # Option 3: Use the batch file instead
    bin\donjon-launcher.bat

Missing dependencies / pip install fails

Symptom: `pip install -r requirements.txt` fails with compilation errors.

Solutions:

- Windows: Install Microsoft Visual C++ Build Tools from Visual Studio
- Linux: Install development headers: `sudo apt install python3-dev build-essential`
- macOS: Install Xcode CLI tools: `xcode-select --install`

If only the `dilithium-py` package fails, the platform will still work but post-quantum license verification will be unavailable (falls back to Ed25519 only).

Port 8443 already in use

Symptom: `OSError: [Errno 98] Address already in use` or similar.

Solution:

    # Find what is using the port
    # Linux/macOS:
    lsof -i :8443

    # Windows:
    netstat -ano | findstr :8443

    # Kill the process or change the port in config.yaml:
    server:
      port: 9443

Virtual environment creation fails

Symptom: `Failed to create venv` during first-run bootstrap.

Solutions:

- Ensure `python3-venv` is installed: `sudo apt install python3-venv` (Debian/Ubuntu)
- Ensure you have write permissions to the platform directory
- If on a USB drive, ensure it is not write-protected
- Try creating the venv manually: `python3 -m venv venv`

## Scan Issues

Scans timing out

Symptom: Scans take extremely long or appear to hang.

Possible causes and solutions:

- Community tier throttling: Community scans have a 500ms delay between checks. Upgrade to Pro for full-speed scanning.
- Too many targets: Reduce the target count or use CIDR notation for subnets.
- Unreachable targets: Verify network connectivity to targets before scanning.
- Deep scan on large network: Use "quick" scan depth for initial assessment, then deep-scan specific targets.

Adjust the per-test timeout in the test runner with `--timeout 120` (seconds).

Network permission errors

Symptom: `Permission denied` or `Operation not permitted` during network scans.

Solution:

- nmap requires root/admin for SYN scans: Run with `sudo` on Linux/macOS or as Administrator on Windows. Alternatively, nmap falls back to TCP connect scans without elevated privileges.
- Firewall blocking: Check local firewall rules and ensure outbound connections to scan targets are permitted.
- Corporate proxy: Configure proxy settings if scanning through a corporate network.

Scanner not found

Symptom: "Scanner X not available" or findings are limited.

Solution: Donjon gracefully degrades when external tools are missing. Install the recommended tools for full scanning capabilities:

Tool | Install Command
--- | ---
nmap | `apt install nmap` / download from nmap.org
nuclei | `go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest`
nikto | `apt install nikto`
testssl.sh | `git clone https://github.com/drwetter/testssl.sh.git`
trivy | `apt install trivy` / download from aquasec

Check available tools: the platform auto-detects tools at startup and reports in the tool discovery phase.

Tier feature blocked during scan

Symptom: "This scanner requires Pro" or "Deep scans are a Pro feature".

Explanation: Community tier is limited to 7 core scanners (network, vulnerability, web, ssl, windows, linux, compliance) and quick/standard depths. Additional scanners and deep scan require Pro or above.

Solution: Upgrade your license tier, or use the available Community scanners.

## License Issues

Invalid license / signature verification failed

Symptom: Log shows "License signature verification failed -- community tier".

Possible causes:

- Corrupted file: The `license.json` file was modified or corrupted during transfer. Re-download or re-copy the original file.
- Wrong file: Ensure you placed the correct `license.json` in `data/license.json`.
- Missing crypto libraries: For v2 licenses, ensure `dilithium-py` and/or `cryptography` packages are installed. At least one is required for signature verification.

    # Install crypto libraries
    pip install dilithium-py cryptography

License expired

Symptom: Log shows "License expired -- community tier".

Solution: Contact donjonsec.com for a renewal. Replace `data/license.json` with the renewed license file and restart the platform.

Machine fingerprint mismatch

Symptom: Log shows "License not valid for this machine -- community tier".

Cause: The license is bound to a different machine's fingerprint.

Solution:

- If you moved the license to a new machine, request a license transfer from support.
- If hardware changed (NIC replacement, hostname change), the fingerprint changed. Contact support with the new fingerprint.
- View current fingerprint via: `GET /api/v1/license`

The fingerprint is a SHA-256 hash of: MAC address + hostname + platform + processor + machine ID.

License revoked

Symptom: Log shows "License has been revoked -- community tier".

Cause: The license ID appears in `data/revoked.json`. This can happen if the license was reported stolen, violated terms, or was replaced.

Solution: Contact support at donjonsec.com to resolve revocation issues.

## AI Issues

AI provider not configured

Symptom: AI queries return errors about missing provider configuration.

Solution: Check `config/active/config.yaml`:

    ai:
      provider: 'template'  # Works without any external service

For Ollama, ensure the service is running: `ollama serve`

For OpenAI, ensure `OPENAI_API_KEY` is set as an environment variable.

Check AI status via API: `GET /api/v1/ai/status`

Test the connection: `POST /api/v1/ai/test`

AI analysis unavailable (Community tier)

Symptom: "AI analysis is a Pro feature".

Cause: AI analysis is a Pro feature. Community Edition uses built-in template-based analysis (no LLM); connecting an AI model requires Pro.

Solutions:

- Community Edition still produces full template-based analysis — no AI key required.
- Upgrade to Pro to connect your own model (local Ollama / llama.cpp / vLLM, any OpenAI-compatible endpoint, or BYO key) — ungated.

The quota counter is stored in `data/ai_quota.json`.

Slow AI responses

Possible causes:

- Ollama backend: Local LLM inference speed depends on hardware. Ensure you have a capable GPU or use a smaller model.
- OpenAI backend: Network latency or API rate limits. Check your internet connection and OpenAI account status.
- Template backend: Should be near-instant. If slow, check disk I/O.

## Database Issues

Database locked

Symptom: `sqlite3.OperationalError: database is locked`

Cause: Multiple processes are trying to write to the SQLite database simultaneously.

Solution:

- Ensure only one instance of Donjon is running
- If the issue persists, stop all Donjon processes and restart
- For multi-user environments, consider upgrading to PostgreSQL (Enterprise tier)

Database corrupted

Symptom: `sqlite3.DatabaseError: database disk image is malformed`

Solution:

    # Attempt recovery
    sqlite3 data/evidence/evidence.db ".recover" | sqlite3 data/evidence/evidence_recovered.db

    # If recovery fails, remove the corrupted database
    # A new empty database will be created on next launch
    mv data/evidence/evidence.db data/evidence/evidence.db.corrupted

Always maintain regular backups to prevent data loss.

Vulnerability intelligence database empty

Symptom: No CVE enrichment data for findings.

Solution: Populate the database:

    # Quick mode (~2 min)
    python3 bin/update-intel.py --quick

    # Full mode (~2 hrs with NVD API key)
    NVD_API_KEY=your-key python3 bin/update-intel.py

    # Check database status
    python3 bin/update-intel.py --status

Get a free NVD API key at nvd.nist.gov for 10x faster downloads.

## Export Errors

Export format not available

Symptom: "This export format requires Pro".

Cause: Community tier only supports CSV and JSON exports. HTML, PDF, SARIF, and XML require Pro or above.

Solution: Use CSV or JSON export, or upgrade your license tier.

PDF export fails

Symptom: PDF generation errors.

Solution: Ensure the required PDF generation library is installed:

    pip install weasyprint
    # OR
    pip install reportlab

On Linux, you may also need: `sudo apt install libpango-1.0-0 libpangocairo-1.0-0`

SARIF export invalid

Symptom: GitHub/GitLab rejects the SARIF upload.

Solution:

- Ensure you are using SARIF v2.1.0 format (Donjon default)
- Validate the file: `python3 -m json.tool data/reports/scan.sarif`
- Check GitHub's SARIF size limits (5000 results per file, 10 MB max)
- Split large results into multiple SARIF files if needed

## Frequently Asked Questions

Can I use Donjon without an internet connection?

Yes. Donjon is designed for air-gapped environments. The platform works completely offline when:

- The AI backend is set to "template" (default)
- The vulnerability intelligence database is pre-populated
- Cloud scanning is disabled (automatic in portable mode)

All license verification happens locally using embedded public keys.

What happens when my license expires?

The platform gracefully falls back to Community tier. You retain full access to Community features (7 core scanners, CSV/JSON export, template-based analysis). Your data and scan history are preserved. Renew your license to restore your previous tier.

Is my data sent to external servers?

Only if you explicitly configure an external AI provider (OpenAI). Even then, data sanitization automatically strips IP addresses and hostnames before sending. The template and Ollama backends keep all data local. License verification is performed locally using embedded public keys -- no license server call is required during normal operation.

Can I run multiple instances simultaneously?

Running multiple instances against the same SQLite database can cause locking issues. For multi-user environments, use PostgreSQL (Enterprise tier) or run separate instances with separate data directories.

How do I reset the platform to factory defaults?

Remove the data directory and reconfigure:

    # Back up license first!
    cp data/license.json ~/license-backup.json

    # Remove data
    rm -rf data/evidence data/reports data/logs

    # Restore license
    cp ~/license-backup.json data/license.json

    # Relaunch - databases will be recreated
    python3 bin/donjon-launcher

What Python version do I need?

Python 3.10 is the minimum supported version. Python 3.11+ is recommended for best performance. Python 3.12 and 3.13 are also supported.

How much disk space does the full vulnerability database require?

The full 7-source vulnerability intelligence database is approximately 732 MB. The base platform requires about 100 MB. Quick mode (`--quick`) downloads a smaller subset sufficient for most use cases.

Can I integrate Donjon with my SIEM?

Yes. Donjon supports several integration methods:

- Webhook notifications: Push alerts to your SIEM webhook endpoint
- SARIF export: Import results into GitHub/GitLab security dashboards
- JSON/CSV export: Import scan results into any system
- Audit log export: Enterprise tier supports audit log export for SIEM integration
- REST API: Pull data programmatically from any system

Need More Help?

If your issue is not covered here, check the GitHub Issues page or contact support at donjonsec.com.