Troubleshooting Guide

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

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

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

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

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

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

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.

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:

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

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.

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

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.

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.

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.

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

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.

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.

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)

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.

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.

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.

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

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

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.

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.

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.

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.

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

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.

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.

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