Troubleshooting search error 502

When you use the advanced search feature in HTML files exported from Dr.Explain, you may encounter error messages with code 502 instead of search results.

A 502 error means the web server cannot connect to the backend service. This usually happens because the backend is not running or the configuration is wrong.

Common causes

Backend crashed: usually due to insufficient memory. Increase memory limits.
Backend not started: start the services with docker compose up -d.
Wrong configuration: the web server is trying to connect to the wrong address or port.
Port conflict: another service is using port 8082.

Step 1: Check if the backend is running

This step requires access to your server via SSH and Docker.

Check the status of your services:

docker compose ps

What you should see: the drexplain-search-backend-controller service should show "Up" in the STATUS column.

If you see "Restarting" or an error code: the backend has crashed. This is often due to insufficient memory. Go to Step 2.

If you see "Up": the backend is running. Go to Step 3.

Step 2: Check for memory issues

This step requires access to your server via SSH and Docker.

Check if the backend ran out of memory:

docker inspect $(docker compose ps -q) --format='{{.Name}}: {{.State.OOMKilled}}'

If you see "true" for any service: the service ran out of memory and crashed.

To fix memory issues:

Stop the services:

docker compose down

Check your available memory:

free

Increase memory limits in your docker-compose.yaml file:

For the solr service, increase SOLR_HEAP.
For the drexplain-search-backend-controller service, adjust environment variable responsible for application's internal memory limits (increase the values specified below, if needed):

environment:

- >-

JAVA_TOOL_OPTIONS=-XX:MaxHeapSize=128m

-XX:MaxMetaspaceSize=10m

-XX:MaxDirectMemorySize=2m

-XX:ReservedCodeCacheSize=8m

-XX:+DisableAttachMechanism

-XX:ThreadStackSize=512k

-XX:+UseSerialGC

Restart the services:

docker compose up -d

Wait a few minutes and test again.

Step 3: Test backend connectivity

This step requires access to your server via SSH.

Try connecting to the backend directly:

curl http://127.0.0.1:8082/ping

What you should see: a message saying "If you see this text, Dr.Explain Search Backend is working..."

If you see this message: the backend is working, but your web server configuration might be wrong. Go to Step 4.

If you get an error: the backend might not be listening on the correct port. Check your docker-compose.yaml file to ensure the backend is configured to use port 8082.

Step 4: Check web server configuration

This step requires access to your server's configuration files.

For nginx servers:

Check that your configuration includes:

location ~ /drexsearch/(.*)$ {

proxy_pass http://127.0.0.1:8082/$1$is_args$args;

}

For Apache servers:

Check that your configuration includes:

RewriteEngine On

RewriteRule ^(?:.*/)?drexsearch/(.*)$ http://127.0.0.1:8082/$1 [P,L]

Common mistakes:

Wrong port number (should be 8082).
Wrong address (should be 127.0.0.1).
Typo in the path pattern.

If you find a mistake: correct the configuration and restart your web server.

Step 5: Check error logs

This step requires access to your server's log files.

For nginx:

sudo tail -f /var/log/nginx/error.log

For Apache:

sudo tail -f /var/log/apache2/error.log

Look for messages like:

"Connection refused" — the backend is not running or not accessible.
"Connection timed out" — the backend is too slow to respond (might be a resource issue).
"No live upstreams" — all backends are down.