Troubleshooting

Installation Troubleshooting¶

This page covers issues specific to installing Faraday. For general runtime troubleshooting, see the Troubleshooting Guide.

Docker Installation¶

Docker Compose file does not work¶

Symptoms: docker compose up exits immediately, services fail to start, or you see YAML parsing errors.

Solutions:

1. Verify you are using Docker Compose v2 (the docker compose plugin):

   docker compose version
   

   If you only have the legacy docker-compose v1, upgrade to Docker Desktop or install the Compose plugin.

2. Ensure you downloaded the correct docker-compose.yaml for your Faraday version. The file syntax has changed between releases.

3. Check for port conflicts before starting:

   ss -tlnp | grep -E '5985|9000|5432'
   

4. If PostgreSQL or Redis ports are already in use by host services, either stop them or modify the compose file to use different ports.

Missing entrypoint.sh¶

Symptoms: Container exits immediately with entrypoint.sh: No such file or directory.

Solutions:

1. Pull the latest image — this was fixed in newer releases:

   docker compose pull
   

2. If the issue persists, verify the image tag matches a published release:

   docker images | grep faraday
   

No web server started in Docker¶

Symptoms: Docker containers are running but no web interface is available on port 5985.

Solutions:

1. Check if the server container started successfully:

   docker compose ps
   docker compose logs faraday-server
   

2. Ensure the PostgreSQL service is healthy before the server starts. Check the db service logs:

   docker compose logs db
   

3. If the database was not initialized, run:

   docker compose run --rm faraday-manage initdb
   

PyPI / pip Installation¶

psycopg2 build failure¶

Error:

Error: You need to install postgresql-server-dev-NN for building a server-side extension
or libpq-dev for building a client-side application.

Fix (Debian/Ubuntu):

sudo apt install -y libpq-dev python3-dev build-essential
pip install psycopg2

Fix (RHEL/CentOS/Fedora):

sudo dnf install -y postgresql-devel python3-devel gcc
pip install psycopg2

Alternatively, use the pre-compiled binary package:

pip install psycopg2-binary

Note: psycopg2-binary is suitable for development. For production, compile psycopg2 from source with system libraries.

pip install fails with wheel build errors¶

1. Ensure you have the latest pip, setuptools, and wheel:

   pip install -U pip setuptools wheel
   

2. Install system build dependencies:

   # Debian/Ubuntu
   sudo apt install -y build-essential python3-dev libffi-dev libssl-dev
   
   # RHEL/CentOS
   sudo dnf install -y gcc python3-devel libffi-devel openssl-devel
   

3. If a specific dependency fails, check if it has a binary wheel available for your Python version and platform.

System Package Installation (Debian/Ubuntu)¶

PostgreSQL service not running after install¶

sudo systemctl start postgresql
sudo systemctl enable postgresql

Verify it is running:

pg_isready

Redis not installed or not running¶

Faraday requires Redis for its Celery task queue. If Redis is missing:

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

Verify:

redis-cli ping
# Should return: PONG

Permission denied during initdb¶

If faraday-manage initdb fails with permission errors:

1. Ensure the PostgreSQL faraday user exists and has CREATEDB privileges:

   sudo -u postgres createuser -d faraday
   

2. If the user already exists, grant the privilege:

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

Alembic log directory missing¶

Error:

FileNotFoundError: [Errno 2] No such file or directory: '/home/faraday/.faraday/logs/alembic.log'

Fix:

mkdir -p ~/.faraday/logs

System Package Installation (RHEL/CentOS)¶

PostgreSQL from PGDG repository¶

The default PostgreSQL packages on RHEL/CentOS may be outdated. Use the PostgreSQL Global Development Group (PGDG) repository:

sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql14-server
sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
sudo systemctl enable --now postgresql-14

SELinux blocks Faraday¶

Do not disable SELinux with setenforce 0. Instead, create a proper policy:

sudo setsebool -P httpd_can_network_connect 1

If Faraday still fails, check the audit log for denials:

sudo ausearch -m AVC -ts recent

And generate a custom policy module:

sudo ausearch -m AVC -ts recent | audit2allow -M faraday
sudo semodule -i faraday.pp

RPM package reported as invalid¶

If dnf or rpm reports the package as invalid:

1. Verify the download was not corrupted:

   sha256sum faraday-server-*.rpm
   

   Compare with the checksum from the download page.

2. Ensure your system architecture matches the package (x86_64).

3. Import the signing key if the package is signed:

   sudo rpm --import https://repo.faradaysec.com/RPM-GPG-KEY-faraday
   

Nix Installation¶

/nix directory exists but is not writable¶

This typically occurs when a previous Faraday .deb or .rpm package installed Nix files. Uninstall the system package first:

sudo apt remove faraday-server    # Debian/Ubuntu
sudo dnf remove faraday-server    # RHEL/CentOS

Then remove the Nix directory and reinstall:

sudo rm -rf /nix

Follow the Nix installation guide to install Nix cleanly.

Sandbox error in containers (LXC, Docker)¶

Error:

Error: while setting up the build environment: mounting /proc: Operation not permitted

This occurs when running Nix inside unprivileged containers. Disable the sandbox:

mkdir -p ~/.config/nix
echo 'sandbox = false' >> ~/.config/nix/nix.conf

Then retry the build.

Database Encoding Issues¶

UTF-8 incompatibility with initdb¶

Error:

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

Fix: Recreate the template1 database with UTF-8 encoding:

-- Connect as postgres superuser
sudo -u postgres psql

-- Recreate template1 with UTF-8
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';
\q

Then retry:

faraday-manage initdb

SSL / HTTPS Issues¶

Server won't start with HTTPS on macOS or Kali¶

Faraday does not handle TLS directly. Do not configure SSL in server.ini. Instead:

1. Run Faraday on HTTP (the default).
2. Place a reverse proxy (NGINX, Caddy) in front of it to terminate TLS.
3. Generate an NGINX config:

   faraday-manage generate-nginx-config
   

Certificate verification failures¶

If Faraday or its components fail with SSL certificate errors when connecting to external services:

1. Install the CA bundle for your OS:

   # Debian/Ubuntu
   sudo apt install -y ca-certificates
   sudo update-ca-certificates
   

2. If using self-signed certificates, add them to the system trust store or set the REQUESTS_CA_BUNDLE environment variable.

General Tips¶

• Always check the version — Many issues are fixed in newer releases. Upgrade before troubleshooting.
• Check logs first — ~/.faraday/logs/ (bare-metal) or docker compose logs (Docker).
• Test database connectivity — faraday-manage sql-shell should open a SQL prompt.
• Test Redis connectivity — redis-cli ping should return PONG.
• Check disk space — Full disks cause silent failures in PostgreSQL and report imports.

For issues not covered here, see the General Troubleshooting Guide or open an issue on GitHub.