Troubleshooting

This page addresses common issues encountered during the deployment and operation of Lodex.

1. Common Docker Issues

Error: Cannot connect to the Docker daemon

• Cause: Docker service is not running or your user lacks permissions.
• Solution: Run sudo systemctl start docker. If permissions are the issue, ensure your user is in the docker group: sudo usermod -aG docker $USER.

Error: Port 80/443 already in use

• Cause: Another web server (like Nginx or Apache) is already running on the host.

• Solution: Modify the ports mapping in your docker-compose.yml to use an available port (e.g., 8080:3000).

2. Database Connectivity

Error: MongoNetworkError: failed to connect to server

Lodex fails to connect to the database, start by verifying the operational status of your database container using the command docker-compose ps. This command allows you to confirm that the MongoDB service is listed as "Up" or "Healthy"; if it is restarting or exited, Lodex will be unable to establish a connection.

Beyond container health, connection failures often stem from misconfigured network parameters. You must verify that the MONGO_HOST environment variable is correctly defined; in a standard Docker Compose setup, this should match the service name of your database (e.g., mongodb). If this host address is incorrect, the internal connection string will fail to resolve.

Finally, if you are utilizing a shared MongoDB instance for multiple Lodex deployments, double-check that the MONGO_DATABASE_PREFIX is unique and consistent for each installation. An inconsistent or missing prefix can lead to authentication errors or unexpected data collisions between different environments.

3. Observation: Pre-calculation Stuck at 50%

If a pre-calculation process remains indefinitely stuck at 50%, it is almost certainly due to a callback communication failure. When Lodex triggers a pre-calculation, it sends a request to an external web service. Once the service finishes processing, it attempts to "call back" to Lodex to deliver the results. If the web service cannot reach your Lodex instance—often because of firewalls, a local network restriction, or an incorrect address—the progress bar will hang at the halfway point, waiting for a response that never arrives. To resolve this, you must adjust the PRECOMPUTED_URL environment variable in your docker-compose.yml. This variable must be set to the publicly accessible URL or the specific network address of your Lodex instance that the web service is capable of reaching. Example Configuration:

services:
  lodex:
    environment:
      # Ensure this URL is reachable by the external web service
      - PRECOMPUTED_URL=https://lodex.your-domain.com

4. Error: "The pipe has not received any data"

If you encounter the error message The pipe has not received any data for 12000 milliseconds in your logs, it indicates that a data processing task has been terminated by a timeout.

Symptoms

• During data enrichment: The process stops abruptly when calling external web services.

• On the dashboard: A chart fails to load, displaying the UI message: "An error occurred while trying to fetch chart data" (French: "Une erreur est survenue en essayant de récupérer les données du graphique").

Why this happens

Lodex uses a streaming pipeline mechanism to process data. To prevent system resources from being locked indefinitely by hanging processes, Lodex is configured to automatically kill any "pipe" that does not produce or receive data within a specific timeframe (defaulting to 12,000ms or 12 seconds).

When performing complex calculations on large datasets or waiting for a slow external API (enricher), this threshold might be reached before the first chunk of data is returned.

Solution: Increasing the Timeout

To allow complex or high-volume tasks to complete, you need to increase the processing timeout. This is done by adjusting the relevant config parameter.

   "ezs": {
        "timeout": 30000
    }

After updating the variable, restart your Lodex for the changes to take effect.

---

Debugging via Logs

If Lodex isn't behaving as expected, the logs are your best friend. Use the following commands to inspect the internal processes:

# View real-time logs for all services

docker-compose logs -f

# View logs for the Lodex application specifically

docker-compose logs -f lodex

# View the last 100 lines of logs

docker-compose logs --tail=100