This page covers frequently encountered issues in S4E On-Prem deployments, with causes and step-by-step solutions.

Installation Errors

Preflight: CPU / RAM / Disk Check Failed

Symptom: setup.sh aborts with a message like:

[ERROR] Minimum requirements not met: RAM=8GB, required=16GB

Solution: The server does not meet the minimum requirements. Upgrade the server or adjust the minimums in setup.conf:

MIN_CPU_CORES=2
MIN_RAM_GB=8
MIN_DISK_GB=10

Harbor Login Failed (401 Unauthorized)

Symptom:

[ERROR] Failed to log in to Harbor registry

Cause: Incorrect HARBOR_USER or HARBOR_PASSWORD in setup.conf.

Solution:

1. Verify the credentials with your S4E account representative.
2. Test manually: docker login harbor.s4e.link -u HARBOR_USER -p HARBOR_PASSWORD
3. Update setup.conf and re-run setup.sh.

Image Pull Failed

Symptom:

Error response from daemon: unauthorized: unauthorized to access repository

Cause: Docker is not logged in to Harbor, or credentials have expired.

Solution:

# Re-login to Harbor
docker login harbor.s4e.link -u <user> -p <password>

# Re-pull images
cd /opt/s4e/setup
docker compose pull
docker compose up -d

Container Startup Errors

Container Exits Immediately (CrashLoop)

Symptom: A container keeps restarting with Restarting status.

Solution:

# Check the exit reason
docker logs s4e-core-1 --tail 50

# Check recent events
docker inspect s4e-core-1 | grep -A5 '"State"'

Common causes:

Volume Error: readdirent: no such file or directory

Symptom:

Error response from daemon: readdirent /var/lib/docker/volumes/s4e_rabbitmq_data/_data: no such file or directory

Cause: The volume's backing directory is missing or inaccessible. This typically happens when the /opt/s4e/volumes directory was manually deleted while Docker's internal volume records still exist, or when the underlying filesystem ran out of inodes/space and the directory entry was lost (volume overflow).

Solution: Use the cleanup script to properly remove Docker volumes, then restart:

bash /opt/s4e/setup/shortcuts/volume_clean.sh
cd /opt/s4e/setup
docker compose up -d

CPUset Error

Symptom:

Error response from daemon: Requested CPUs are not available - requested 6-31, available: 0-27

Cause: SCAN_CPUSET or CRAWLER_CPUSET in .env specifies CPU cores that don't exist on this server.

Solution: Let setup.sh recalculate, or manually update .env:

# Check available cores
nproc  # e.g. 28

# Update .env
nano /opt/s4e/setup/.env
# Set SCAN_CPUSET and CRAWLER_CPUSET within range 0 to (nproc-1)
# Example for 28 cores: SCAN_CPUSET=14-27

docker compose up -d --no-deps scan crawler

Database Errors

Connection Refused to PostgreSQL

Symptom: Services log could not connect to server: Connection refused on port 5432.

Solution:

# Check if DB container is running
docker ps | grep s4e-db

# Check DB logs
docker logs s4e-db-1 --tail 30

# Test connectivity from another container
docker exec s4e-core-1 nc -zv db 5432

If the DB container is not running:

cd /opt/s4e/setup
docker compose up -d db

High Dead Tuple Percentage (Slow Queries)

Symptom: Adminer or application queries are slow. The database has high dead tuple counts.

Solution: Run VACUUM ANALYZE on affected tables:

docker exec s4e-db-1 psql -U <POSTGRES_USER> -d <POSTGRES_DB> -c "VACUUM ANALYZE;"

Check dead tuples:

SELECT relname, n_dead_tup, n_live_tup,
       round(n_dead_tup::numeric/NULLIF(n_live_tup+n_dead_tup,0)*100,1) AS dead_pct
FROM pg_stat_user_tables
ORDER BY n_dead_tup DESC LIMIT 20;

Nginx Errors

502 Bad Gateway

Symptom: Browser shows 502 Bad Gateway when accessing a subdomain.

Cause: Nginx is running but the backend Docker container is down or not listening on the expected port.

Solution:

# Check which container is down
docker ps --filter status=exited

# Restart it
cd /opt/s4e/setup
docker compose up -d <service-name>

# Test nginx config
sudo nginx -t
sudo systemctl reload nginx

SSL Certificate Error in Browser

Symptom: Browser shows an untrusted certificate warning.

Cause: S4E On-Prem uses a self-signed certificate generated during installation.

Solution (for testing): Click "Advanced → Proceed" in the browser, or add the certificate to your system's trusted store:

# Copy the certificate to your Mac
scp USER@SERVER:/opt/s4e/setup/nginx/ssl/cert.pem ~/s4e-cert.pem

# Add to macOS Keychain
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/s4e-cert.pem

Solution (for production): Replace the self-signed certificate with one from a trusted CA (Let's Encrypt or your organization's CA).

401 Unauthorized on Admin Pages

Symptom: Accessing adminer, rmq, admin, or git subdomains prompts for a username and password.

Cause: These pages are protected by HTTP Basic Auth, which is intentional.

Solution: The credentials are: - Username: admin - Password: Printed at the end of installation and stored in /opt/s4e/setup/.env as HTPASSWD_PLAIN_PASSWORD (or similar).

Scan Errors

Scan Templates Not Found

Symptom: Scans fail with "no templates available" or similar.

Cause: s4e-scan-func-puller has not yet pulled templates from S4E Cloud, or the pull failed.

Solution:

# Check puller logs
docker logs s4e-scan-func-puller-1 --tail 50

# Verify the pull volume has content
ls /opt/s4e/volumes/s4e-func/

If the pull is failing with a 401 or 404:

# Verify your API key and cloud URL
docker exec s4e-scan-func-puller-1 env | grep -E "TOKEN|S4E_CLOUD"

DNS Resolution Failures in Scans

Symptom: Scans against internal hostnames fail with DNS errors.

Cause: WORKER_DNS is set to an external DNS server that cannot resolve your internal domains.

Solution: Set WORKER_DNS to your internal DNS server in .env:

WORKER_DNS=192.168.1.1    # your internal DNS
DNS_RESOLVERS=192.168.1.1

Restart affected services:

docker compose up -d scan crawler scan-func-puller

Scheduler / Sync Errors

Action Catalog Sync: sync_disabled

Symptom: tasks.onprem.db-sync.action_catalog returns status: sync_disabled.

Cause: ENABLE_DATABASE_SYNC is set to false.

Solution:

# Check current value
docker exec s4e-scheduler_general-1 env | grep ENABLE_DATABASE

# Update .env
nano /opt/s4e/setup/.env
# Set: ENABLE_DATABASE_SYNC=true

docker compose up -d --no-deps scheduler_general

Telemetry Errors

Symptom: Scheduler logs show 401 or 403 errors when sending telemetry.

Cause: The TOKEN in .env is invalid, expired, or not authorized for on-prem.

Solution: Obtain a valid API key from https://app.s4e.io → Settings → API Tokens and update .env:

TOKEN=your-new-api-key

Restart the scheduler:

docker compose up -d --no-deps scheduler_general

Performance Issues

Adminer / UI Is Slow

Symptom: Web interface and database UI respond slowly.

Common causes and fixes:

Getting Help

If you cannot resolve an issue using this guide:

1. Collect diagnostic information:

   # Container status
   docker ps -a > /tmp/containers.txt
   
   # Recent logs for the failing service
   docker logs s4e-core-1 --tail 200 > /tmp/core-logs.txt
   
   # Disk and memory
   df -h > /tmp/disk.txt
   free -h > /tmp/mem.txt
   

2. Check the logs guide for how to read structured JSON logs.

3. Contact S4E support with the collected information and the output of cat /opt/s4e/setup/.env (redact passwords before sharing).