Why is Adminer.php blank? Renaming it works fine though? Analysis of the cause and a 3-step solution.

Yesterday afternoon, I was configuring the Adminer database management tool on the server. Adminer is lightweight and easy to use; a single PHP file does the job, unlike phpMyAdmin which requires a bunch of dependencies. I downloaded the latest version from the official website, uploaded it to the server, set the permissions, and opened my browser, ready to check it out.

Then, everything went blank.

I refreshed the page three times, my fingers aching from pressing F5 so many times. Still nothing. I opened the browser's developer tools; it showed a 200 OK error, but the response body was empty. I was completely stunned. What was going on?

I thought about it for a moment. Could it be a file permission issue? I checked, and it was 755. Could it be a PHP version incompatibility? I checked, and it's PHP 8.2, which is fine. Could the file itself be faulty? I downloaded a new copy, overwrote it, and it's still blank.

For some inexplicable reason, I thought, why not try changing my name?

I renamed adminer.php to adminer1.php and refreshed the page.

Access was successful.

I was genuinely baffled. The same file, the same code, the same server, and it's accessible just by changing the name? What kind of mystical logic is this?

The issue of a blank adminer.php file

Later I realized that this wasn't some kind of superstition; it was PHP caching that was causing the problem.

OPcache, short for Opcode Cache, is a performance optimization extension for PHP. Its principle is simple: PHP is an interpreted language, and each request requires the PHP code to be compiled into opcode before execution. OPcache caches the compiled result in memory, allowing subsequent requests to use the cached version directly without recompilation, resulting in a significant performance improvement.

But that's where the problem lies.

Previously, adminer.php displayed "File not found" (I had uploaded the wrong file), and OPcache had cached the compiled result of that incorrect content. Later, I replaced adminer.php with the correct code, but OPcache ignored it and continued to read the old cache from memory, resulting in a blank page or the old error message.

When you rename it to adminer1.php, it becomes a completely new file path for OPcache, and it will reload and resolve it correctly.

It's like you've already gotten a new book, but the library's index card still has the old book's call number on it. When you go to look for it on the shelf, of course, it's empty. But if you change the book's title, the library will create a new index card for you, and then you can find it.

Reason 1: OPcache cache causes blank spaces

How to deal with it?

Restart the PHP-FPM service and clear the OPcache cache.

# 查看正在运行的PHP版本
php -v

# 重启对应的PHP-FPM（例如PHP 8.5）
sudo systemctl restart php8.5-fpm

# 或者重启所有PHP-FPM服务
sudo systemctl restart php*-fpm

After restarting, rename the file back to adminer.php, refresh the webpage (it's recommended to press Ctrl+F5 to force a browser refresh), and the problem should be solved.

But the story isn't over yet.

After restarting PHP-FPM, I changed the adminer.php file back, refreshed the page, but it was still blank. I was completely baffled.

Reason 2: Nginx configuration rule restrictions

This leads to the second possible reason.

The Nginx configuration file may have special rules restricting adminer.php.

I previously configured Fail2Ban in the HestiaCP panel and wrote an exact match rule for adminer.php to prevent brute-force attacks. The rule hardcoded the filename adminer.php, so once you renamed it to adminer1.php, you bypassed this Nginx rule and could access it normally.

The troubleshooting method is simple: search for hard-coded entries in the Nginx configuration.

sudo grep -rn "adminer.php" /etc/nginx/

If you find rules like `location = /adminer.php { … }`, it means Nginx is handling this specific filename specially. Just delete or modify it.

Reason 3: PHP error display settings

The third reason is more subtle.

The PHP script is intercepted or throws an error, but the page disables error display (display_errors = Off). In a production environment, PHP hides errors by default, displaying a blank page. If your entry file (e.g., index.php) crashes for some reason while trying to include "./adminer.php", the page will simply turn blank.

In this situation, checking the error log is the most reliable method:

# 查看Nginx错误日志
sudo tail -n 20 /var/log/nginx/error.log

# 或者查看HestiaCP对应域名的error日志
sudo tail -n 20 /var/log/nginx/domains/adminer.domain.com.error.log

The log will tell you the real reason for the white screen.

To be honest, I finally found the problem by checking the error.log. It turned out that adminer.php was calling a non-existent PHP extension, and display_errors was off, so the page was blank, but the error log recorded it clearly.

Solutions and troubleshooting steps

This incident has left a deep impression on me.

Technical problems are often not as simple as they seem on the surface. A blank adminer.php file may seem like a file issue at first glance, but digging deeper could reveal a caching problem, further down the line it could be a configuration issue, and still further down the line it could be a problem with the code itself.

If you're not a programmer, you might think these things are irrelevant to you. But think about it: every app you use, every webpage you visit, has a similar system running behind the scenes. Caching, configuration, error handling—these concepts are actually everywhere.

Just like us humans. Many times, the "symptoms" we exhibit, such as procrastination, anxiety, and irritability, may seem like laziness on the surface, but digging deeper, they may be due to unclear goals, further digging, a fear of failure, and even deeper, a mindset shaped by childhood experiences.

Only by finding the true root cause can we prescribe the right medicine.

Finally, if you also encounter the problem of a blank adminer.php file, check it in this order:

First, restart PHP-FPM and clear the cache, then check the Nginx configuration, and finally check the error.log.

In most cases, the first two steps are enough to solve the problem.

Of course, if that still doesn't work, then check the error.log.

It will tell you the answer.

Since you've read this far, if you found it helpful, please like and share it. If you want to receive updates first, you can also follow me!

Thank you for reading my article. See you next time.