Troubleshooting

Troubleshooting¶

This guide provides solutions for common problems with Faraday. If your problem is not listed below, open an issue on GitHub.

Before You Begin¶

Check your version — Run faraday-server --version and verify you are on the latest release at GitHub Releases. Upgrading often resolves known issues.
Enable debug logging — Set debug=true in ~/.faraday/config/server.ini under [faraday_server] and restart.
Check the logs — Logs are at ~/.faraday/logs/ (bare-metal) or accessible via docker compose logs <service> (Docker).
Run the status check — faraday-manage status-check provides a quick health report.

Docker Issues¶

Docker Compose fails to start¶

Symptoms: docker compose up exits with errors, services fail to become healthy, or containers restart in a loop.

Solutions:

Ensure you are using Docker Compose v2 (the docker compose plugin, not the legacy docker-compose v1):
```
docker compose version
# Should show: Docker Compose version v2.x.x
```
Pull the latest images:
```
docker compose pull
```
Verify the docker-compose.yaml syntax matches the version you downloaded. If you modified the file, compare with the original from the release.
Check that no other service is using the required ports (5985, 9000):
```
ss -tlnp | grep -E '5985|9000'
```
If you see database errors, the PostgreSQL data volume may be corrupted. Try recreating from scratch:
```
docker compose down -v   # WARNING: This deletes all data
docker compose up -d
```

Port 9000 unreachable (WebSocket service)¶

Symptoms: The WebSocket service on port 9000 does not respond. Real-time updates in the UI stop working. Agents cannot connect.

Solutions:

Check that the WebSocket service is running:
```
docker compose ps
```
All services should show Up (healthy).
If the WebSocket service is not starting, check its logs:
```
docker compose logs faraday-server
```
Verify that port 9000 is mapped in your docker-compose.yaml:
```
ports:
  - "5985:5985"
  - "9000:9000"
```

If behind a reverse proxy (NGINX), ensure WebSocket upgrade headers are configured:

location /dispatcher {
    proxy_pass http://localhost:9000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Cannot find initial password in Docker¶

Symptoms: After docker compose up, you cannot log in to the web UI because the password is unknown.

Solutions:

Check the change-password service logs:
```
docker compose logs change-password
```

If no password was printed, reset it manually:

docker compose run --rm faraday-manage change-password

If the faraday-manage service is not available, exec into the server container:
```
docker compose exec faraday-server faraday-manage change-password
```

Database initialization fails in Docker¶

Symptoms: The server container exits with database errors on first startup.

Solutions:

Ensure the db (PostgreSQL) service is fully started before the server:
```
docker compose logs db
```
Look for: database system is ready to accept connections

If you see permission errors, check that the PostgreSQL data volume has correct ownership:

docker compose down
docker volume rm <project>_faraday_postgres
docker compose up -d

For custom PostgreSQL configurations (external DB, cloud-managed), set the connection string in your environment or server.ini:
```
POSTGRES_USER=faraday
POSTGRES_PASSWORD=yourpassword
POSTGRES_HOST=your-db-host
POSTGRES_DB=faraday
```

Cannot access the Web GUI¶

Verify the server is running:
```
faraday-manage status-check
```
If the server is not running, start it:
```
faraday-server
```
Or in Docker:
```
docker compose up -d
```
Access the UI at http://localhost:5985 (or your configured address). If you changed bind_address, use that address instead.

How to reset the password¶

faraday-manage change-password

Enter the username (default: faraday) and the new password when prompted.

In Docker:

docker compose run --rm faraday-manage change-password

2FA field does not accept paste¶

If the two-factor authentication input field does not accept Ctrl+V paste, type the code manually or use your browser's autofill functionality.

flask_login / flask_security compatibility errors¶

Symptoms: Login fails with errors about fs_uniquifier or flask_login version mismatches.

Solutions:

Ensure you have compatible versions installed. Check requirements.txt in the release:
```
pip show flask-login flask-security-too
```
If using pip, install the exact versions specified:
```
pip install -r requirements.txt
```
After upgrading flask-security, run database migrations:
```
faraday-manage migrate
```

Database Issues¶

Database migration failures during upgrade¶

Symptoms: After upgrading Faraday, you see errors like:

ERROR: relation 'vulnerability' does not exist

or Alembic migration errors.

Solutions:

Always back up before upgrading:

pg_dump -U faraday faraday > faraday_backup_$(date +%F).sql

Check current migration status:

faraday-manage migrate --revision heads

If a migration failed partway, try running it again:
```
faraday-manage migrate
```
If the database is in an inconsistent state, restore from backup and try the upgrade again:
```
psql -U faraday -d faraday < faraday_backup.sql
```
For persistent migration issues, check GitHub Issues for your specific error message.

`faraday-manage initdb` fails¶

Symptoms: Database initialization errors during first setup.

Solutions:

Ensure PostgreSQL is running and accessible:
```
pg_isready
```

Verify the PostgreSQL user has CREATEDB permission:

sudo -u postgres psql -c "ALTER USER faraday CREATEDB;"

If you see encoding errors:

ERROR: new encoding (UTF8) is incompatible with the encoding of the template database (SQL_ASCII)

Fix the template database encoding:

UPDATE pg_database SET datistemplate = FALSE WHERE datname = 'template1';
DROP DATABASE template1;
CREATE DATABASE template1 WITH TEMPLATE = template0 ENCODING = 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';
UPDATE pg_database SET datistemplate = TRUE WHERE datname = 'template1';

Then retry faraday-manage initdb.

If the Alembic log directory is missing:

FileNotFoundError: No such file or directory: '/home/faraday/.faraday/logs/alembic.log'

Create the directory:

mkdir -p ~/.faraday/logs

Error while backing up the database¶

If pg_dump fails with:

FATAL: role "root" does not exist

Switch to the postgres system user first:

sudo -u postgres pg_dump faraday > faraday_backup.sql

Changing the database password breaks Faraday¶

After changing the PostgreSQL password, update the connection string in ~/.faraday/config/server.ini:

[database]
connection_string=postgresql+psycopg2://faraday:NEW_PASSWORD@localhost/faraday

Then restart the server.

Report Import & Plugins¶

Report is not being imported¶

Verify your tool is listed in the Plugin List. If not, you can create a custom plugin or request support.
Force plugin detection — Rename the report file with the plugin suffix:
```
myreport_faraday_Nmap.xml
myreport_faraday_Nessus.nessus
myreport_faraday_Nuclei.json
```
Then upload via the Web UI or copy to ~/.faraday/reports/{workspace_name}/.

Check the server logs for plugin parsing errors:

grep -i "plugin\|import\|report" ~/.faraday/logs/faraday-server.log

Nuclei reports fail to import¶

Symptoms: Nuclei scan results are not imported, or imported data is missing fields.

Solutions:

Use Nuclei's JSON output format, not the default stdout or markdown:
```
nuclei -u target.com -json -o nuclei_results.json
```
Ensure you are using a compatible version of faraday-plugins. Update with:
```
pip install -U faraday-plugins
```
If sensitive fields are missing from vulnerability details, verify your Nuclei template includes severity and description fields.

Nessus import issues¶

Export from Nessus in .nessus format (native XML), not CSV or HTML.
If severity levels are not recognized, ensure the .nessus file contains the risk_factor and severity elements.
For agent-based Nessus imports, verify the agent executor configuration includes correct Nessus API credentials.

Nmap XML report upload fails¶

Ensure the report is in XML format (-oX flag in Nmap):
```
nmap -sV -oX scan_results.xml target.com
```
Verify the XML is well-formed (not truncated by an interrupted scan).

Try importing via the CLI for more detailed error output:

faraday-cli tool report scan_results.xml -w workspace_name

Large reports cause errors or timeouts¶

For reports over 50–100 MB:

Split the scan into smaller segments (by subnet, port range, or target group).
Increase the Celery worker timeout if you control the deployment.
Upload via the API with chunked processing if available.
Monitor the reports queue for stuck tasks:
```
faraday-manage status-check
```

A plugin added too much information¶

Go to the Activity Feed in the Web GUI, filter vulnerabilities by the relevant criteria (severity, date, service), select them, and click Delete.

Agents & Dispatcher¶

Agent cannot connect to Faraday server¶

Symptoms: The agent dispatcher shows ConnectionError: Unexpected status code 503 or Cannot connect to host :9000.

Solutions:

Verify the Faraday server and WebSocket service are running and port 9000 is accessible:
```
curl -s http://localhost:9000/status
```
Check the agent dispatcher configuration (~/.faraday/config/dispatcher.ini or environment variables):
server_url must point to the Faraday server (e.g., http://faraday-server:5985)
websocket_url must point to the WebSocket service (e.g., ws://faraday-server:9000)
Ensure the agent's API token is valid and not expired. Re-register the agent if needed.
If running the dispatcher in Docker, ensure it is on the same Docker network as the Faraday server:
```
networks:
  - faraday_network
```
Check for websockets library version mismatches:
```
pip show websockets python-socketio
```

Agent dispatcher Docker image is outdated¶

The :latest tag for the dispatcher image may lag behind releases. Pin to a specific version:

image: faradaysec/faraday_agent_dispatcher:3.7.0

Check Docker Hub for the latest tag.

Executor errors (Nmap, Nuclei, Nessus, OpenVAS)¶

Verify the executor's dependencies are installed inside the executor environment.
Check executor logs for specific error messages.
Test the executor command manually outside of Faraday to verify it works.
For Nessus executors, the agent supports API key authentication (not just username/password). Check the executor parameters.

"Run" button is greyed out¶

Ensure the agent is in Connected status in the Agents panel.
Verify the workspace has at least one executor configured.
Check that your user has permissions to run agents in the current workspace.

How to delete an agent¶

Use the API:

curl -X DELETE http://localhost:5985/_api/v3/agents/{agent_id} \
  -H "Authorization: Token <your_token>"

Or use the Web UI Agents panel (Professional/Corporate editions).

CLI Issues¶

CLI cannot connect to Faraday server¶

Verify the CLI is configured with the correct server URL:
```
faraday-cli auth
```
If connecting to a Docker deployment from outside the Docker network, use the host's IP/hostname, not the internal Docker service name.
If using HTTPS behind a reverse proxy, ensure the CLI trusts the certificate:
```
faraday-cli auth --url https://faraday.example.com --ignore-ssl
```

CLI returns 500 errors when sending data¶

Check the server logs for the actual error:

grep ERROR ~/.faraday/logs/faraday-server.log | tail -20

Verify the target workspace exists and you have write permissions.
Ensure the report format is supported — try uploading the same file via the Web UI to isolate whether the issue is CLI-specific.

CLI fails to detect report format¶

If faraday-cli tool report says "Failed to detect report":

Specify the plugin explicitly:

faraday-cli tool report output.json --plugin-id nuclei

Update faraday-plugins to the latest version:
```
pip install -U faraday-plugins
```

Server Configuration¶

Can't access Faraday Server remotely¶

Edit ~/.faraday/config/server.ini:

[faraday_server]
port=5985
bind_address=0.0.0.0

Restart the server. If using a firewall, ensure port 5985 (and 9000 for WebSocket) is open.

NGINX reverse proxy configuration¶

Ensure your NGINX config includes proper proxy settings:

server {
    listen 443 ssl;
    server_name faraday.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:5985/;
        proxy_redirect http:// $scheme://;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /dispatcher {
        proxy_pass http://localhost:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Generate a baseline config with:

faraday-manage generate-nginx-config

SMTP is not being saved from the UI¶

Update SMTP settings manually via the CLI:

faraday-manage settings -a update smtp

Set each field (host, port, username, password, sender, ssl, enabled) as prompted.

LDAP reconfiguration (after Faraday v3.15)¶

LDAP settings were moved to a database-backed configuration system. Reconfigure via CLI:

faraday-manage settings -a update ldap

Update all fields according to your directory server configuration. Key fields include:

enabled — True to activate LDAP
server — LDAP server hostname or IP
port — Usually 389 (LDAP) or 636 (LDAPS)
use_ldaps / use_start_tls — Enable TLS
domain_dn — Base DN for searches (e.g., DC=company,DC=com)
user_attribute — Usually sAMAccountName (AD) or uid (OpenLDAP)

Executive reports disappeared after enabling markdown¶

Markdown report templates are stored at:

~/.faraday/executive_reports_templates/markdown_generic
~/.faraday/executive_reports_templates/markdown_grouped

Verify these directories exist and contain your template files.

Python Dependency Issues¶

ImportError: cannot import name 'JSONEncoder' from 'flask.json'¶

This occurs when Flask is updated beyond the version Faraday was tested with. Pin dependencies to the versions in requirements.txt:

pip install -r requirements.txt

AttributeError: 'GreenSocket' has no attribute 'sendmsg'¶

This is a gevent/greenlet compatibility issue. Ensure matching versions:

pip install -U gevent greenlet

UnicodeEncodeError: 'ascii' codec can't encode character¶

If the database encoding is ASCII instead of UTF-8:

Check the current encoding:

faraday-manage sql-shell

SHOW SERVER_ENCODING;

If the encoding is not UTF-8, you must migrate the database:
Dump the database
Drop and recreate with UTF-8 encoding
Reload the data

Startup & Performance¶

Server fails to start on Kali Linux¶

Check for port conflicts — Kali may have other services on port 5985:
```
ss -tlnp | grep 5985
```

Ensure all dependencies are installed:

sudo apt update && sudo apt install -y postgresql redis-server

Start required services:

sudo systemctl start postgresql redis-server

If using HTTPS and the server fails to start, verify your SSL certificates are valid and readable.

Redis connection refused¶

Verify Redis is running:
```
redis-cli ping
```
Should return PONG.

If Redis is not installed:

sudo apt install redis-server
sudo systemctl enable --now redis-server

Check the Redis connection settings in server.ini if using a non-default host/port.

Port 5985 already in use¶

Another process is using the default Faraday port:

ss -tlnp | grep 5985

Either stop the conflicting process or change Faraday's port in server.ini:

[faraday_server]
port=5986

Still need help?¶

Community edition: GitHub Issues
Professional / Corporate: Support Portal
FAQ: Frequently Asked Questions
Installation issues: Installation Troubleshooting

Troubleshooting