Troubleshooting search error 500

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

A 500 error means the web server encountered an unexpected problem while processing your request.

Common causes

Permission issues: the web server cannot read files or access directories.
Configuration syntax error: a typo or formatting mistake in the configuration file.
Rewrite loop: URL rewriting rules create an infinite loop.
SSL certificate issues: the web server cannot read or validate SSL certificate files.

Step 1: 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 these messages:

"Permission denied" — the web server cannot access files. Go to Step 2.
"rewrite loop" — your configuration has an infinite loop. Go to Step 3.
"Invalid command" or "syntax error" — there's a mistake in your configuration. Go to Step 4.

Step 2: Check file permissions

This step requires access to your server via SSH.

Check the permissions on your files:

ls -la /path/to/your/html/files

What you should see: the web server user (usually nginx, www-data, or apache) should have read permissions that look like drwxr-xr-x. The r and x among the last three characters of the permissions text mean the files are readable and the web server can list the contents of the folder.

If permissions are wrong: contact your server administrator to fix them.

Step 3: Check for rewrite loops

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

Common nginx mistake that causes loops:

# WRONG - creates infinite loop

rewrite ^/page(.*)$ /page$1 last;

Correct configuration:

# GOOD - use 'break' instead

rewrite ^/page(.*)$ /page$1 break;

If you find a loop: correct the rewrite rule and restart your web server.

Step 4: Check configuration syntax

This step requires access to your server via SSH.

For nginx:

sudo nginx -t

You should see:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

For Apache:

sudo apache2ctl configtest

You should see:

Syntax OK

If you see errors: fix the syntax errors mentioned in the error message.

Step 5: Test the backend in browser

If the web server configuration appears correct, the error might be coming from the backend service. Follow these steps to check if the backend is working properly.

Open your documentation in a web browser.
Click on any topic in the menu.
In the browser's address bar, change the URL by removing the filename at the end and adding /drexsearch/ping, for example:

Change from: http://your-server.com/docs/some-file.htm

Change to: http://your-server.com/docs/drexsearch/ping
Press Enter.

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, The 500 error is likely caused by your web server configuration. Review the steps above carefully.

If you see this error (or similar):

{"error":"URL \"/drexsearch/ping\" is invalid..."}

This means your web server is adding an extra prefix (/drexsearch in example above) when forwarding to the backend. Check your web server configuration.

If you get a different error: the backend might not be running. Continue with the next step to check if the backend service is running.

Step 6: Test the backend directly

If you have access to the server, connect to it (e.g. via SSH) and open a terminal, then try this command:

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 is not configured to forward requests correctly. Check your web server configuration.

If you get an error: the backend might not be running. Go to Troubleshooting search error 502 to check if the backend service is running.

Step 7: Check backend logs

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

Check if the backend is having problems:

docker compose logs drexplain-search-backend-controller

Look for: errors, exceptions, or other issues that might explain the 500 error.

If you see errors: address the specific errors mentioned in the logs. Common issues include memory problems, connection errors, or configuration mistakes.