Troubleshooting

Issue	Solution
Misconfigured Application - Reinstallation Required	1. Navigate to the datafocus folder: > cd datafocus 2. Shut down and remove all services: > docker compose down -v 3. Delete the entire datafocus folder.To clean up the entire Docker environment (optional): > docker system prune -af
Cannot Access User Interface / CORS Errors	If you cannot reach the user interface or encounter CORS errors: 1. Restart the router container: > docker compose restart router 2. Verify the hostname configuration as described in Hostname Configuration. 3. Ensure ports 80 and 443 are open on the server.
"Compose" is Not a Docker Command	If you encounter the error compose is not a docker command: This likely indicates that Docker Compose is not properly installed or configured. Revisit the installation steps to ensure Docker Compose is correctly set up on your system.
Invalid Parameter: redirect_uri	If you receive an Invalid Parameter: redirect_uri error: 1. Double-check the configurations outlined in Keycloak Configuration. 2. Verify that the Root URL and Valid Redirect URIs are properly set according to your hostname.
Kafka: Message Size Too Large ([Error 10] MessageSizeTooLargeError)	If you see this error in the frontend or logs, the message exceeds Kafka limits. 1. Increase the broker limit in docker-compose.yml by raising the environment variable in the Kafka service: KAFKA_MESSAGE_MAX_BYTES: 5242880 → set to a higher value (e.g., 10485760 for 10 MB or 20971520 for 20 MB). 2. Apply changes: docker compose up -d
Database: "could not resize shared memory segment ... No space left on device" / DiskFullError	Despite the message, the server disk is not full. PostgreSQL uses /dev/shm for parallel queries and Docker allocates only 64 MB by default. 1. Check the current size: > docker exec postgresql df -h /dev/shm 2. Ensure the postgresql service in docker-compose.yml has: shm_size: ${POSTGRES_SHM_SIZE:-2gb} 3. Recreate the container — a restart is not enough, because this setting is applied when the container is created: > docker compose up -d postgresql
Scan Stops Progressing / unstructured-worker Restarts Repeatedly	Scan workers monitor system-wide memory usage and shut themselves down when it stays above 85%, to prevent an out-of-memory condition on the server. 1. Check the restart count of the workers: > docker compose ps unstructured-worker 2. Check total memory usage on the host with free -h while a scan is running. 3. If memory usage is high, identify what else is consuming it. Software unrelated to Data Focus — monitoring agents, backup jobs, log collectors — is the usual cause. The server should be dedicated to Data Focus. 4. Reducing WORKER_REPLICAS or SCAN_MAX_WORKERS lowers memory demand if the server cannot be freed up.
Clock-Related Failures (token, certificate or Kafka errors)	Errors that appear across several services at once — expired or not-yet-valid tokens, TLS certificate validation failures, Kafka connection problems — are often caused by clock drift on the server. 1. Verify synchronization: > timedatectl status 2. System clock synchronized must report yes. If it does not, install and enable an NTP client (chrony or systemd-timesyncd) and restart the stack.