Common WordPress Troubleshooting Guide

Introduction

WordPress is a popular Content Management System (CMS) that lets you build websites, portfolios, and eCommerce applications. While it’s a user friendly platform, there are common WordPress errors that make it a hard platform to troubleshoot depending on the amount of errors displayed to either the site visitor or administrator dashboard.

Depending on the error source, most WordPress errors are a result of the underlying infrastructure that functions to deliver your application to the site visitors. In this case, if your web server configuration breaks, your WordPress site automatically shows an error to the site visitors, fix it by troubleshooting the web server functionalities.

Frontend WordPress errors are minimal warnings that don’t usually break your site structure, but greatly impact the user experience each time your site loads to a new visitor. In this case, you should scan common plugin, WordPress core, and theme errors to avoid any additional errors.

This article explains common backend and frontend WordPress errors and how you can troubleshoot them to improve your site's reliability.

Prerequisites

Before you begin, make sure you:

• Have an active WordPress site. If not, deploy a OneClick WordPress server using the Vultr Marketplace application

• Log in to your WordPress site as an administrative user

    https://example.com/wp-admin
  

• Have SSH or terminal access to the WordPress server

Common WordPress Errors

Many WordPress errors get discovered each time a new major update rolls out. Depending on your exact error, below are 10 of the most common WordPress errors known to affect site performance, search rankings, reliability, and sometimes lead to total data loss.

• Error Establishing a Database Connection
• Your Connection is Not Private (Invalid SSL Certificate)
• WordPress White Screen of Death (Blank Screen)
• Internal Server Error (500)
• 404 Page Not Found
• Upload: Failed to Write File to Disk” Error
• 503 Service Unavailable Error
• The Site is Experiencing Technical Difficulties
• 403 Forbidden Error
• Mixed Content Error

Troubleshoot Common WordPress Errors

To troubleshoot and fix common WordPress errors, you must know the exact source of the error before you take steps to find a solution. Commonly, you should follow the basic troubleshooting steps described in this section to fix WordPress errors.

View the WordPress Logs

WordPress logging allows you to view errors in a single output file. By default, the feature is inactive, enable it to keep track of any WordPress debugging errors that may display and affect your site performance as described below.

1. Navigate to your WordPress web root directory. For example /var/www/html, /var/www/public_html, /var/www/example.com/

    $ cd /var/www/html
   

2. Using a text editor of your choice such as nano, edit the wp-config.php file

    $ nano wp-config.php
   

3. Add the following directive at the end of the file to activate WordPress logging

    define('WP_DEBUG_LOG', true);

   Save and close the file

4. Switch to the wp-content directory

    $ cd /wp-content/
   

5. List files and verify that a new debug.log file is available in the directory

    $ ls
   

6. View the debug.log file to access the WordPress error logs

    $ cat debug.log

   Each time your WordPress site runs into an error. It’s logged to the debug.log file. Always view the file to identify the exact source of the error. For example:

    [2023-07-07 12:00:01] PHP Fatal error:  Call to undefined function get_non_existent_function() in /var/www/example.com/wp-content/plugins/custom-plugin/plugin-file.php on line 644

   The above error shows that your custom-plugin returns an error on line 644. You can edit the plugin file to correct it, or disable the plugin to prevent any additional errors.

Activate WordPress Debugging

WordPress debugging enables the display of errors on your WordPress site for troubleshooting by an administrator. Usually, these appear when any of the installed themes or plugins are poorly coded or returns runtime errors. By default, WordPress debugging is not active, enable it as described in the steps below.

1. Edit the wp-config.php file

    $ nano wp-config.php
   

2. Add the following directives at the end of the file

    define('WP_DEBUG_DISPLAY', false);
    define('WP_DEBUG_LOG', true);

   Save and close the file

   The above directives turn on WordPress debugging and disable errors from appearing on your site visitor's screen. This allows you to know the exact source of a WordPress error and gives you enough details to correct it and avoid any additional errors in your application.

View the Web Server Logs

The web server is the root component of your WordPress site that keeps it running. Most WordPress deployments either use Apache, Nginx, OpenLiteSpeed, or Caddy as the web server application. Depending on your deployment, check the web server logs to identify the source of a WordPress error as described in the steps below.

1. Visit the /var/log/ directory

    $ cd /var/log
   

2. Switch to the web server logs directory. For example Nginx

    $ cd /var/log/nginx
   

3. View the error log

    $ sudo cat error.log

   If your WordPress configuration uses a custom Nginx error log such as example.com.error.log, view the file contents to display the application's specific error.

    $ sudo cat example.com.error.log

   If your WordPress site has a web server-related error. It should display in your log file entries

    2023/08/07 12:00:00 [error] 12345#0: *6789 open() "/var/www/example.com/productabc.html" failed (2: No such file or directory), client: 192.0.2.100, server: example.com, request: "GET /missing-page.html HTTP/1.1", host: "example.com"

   The above error shows that the web server displays a 404 error because the productabc.html file is unreadable or unavailable in the WordPress web root directory.

Enable WordPress Recovery Mode

WordPress recovery mode allows you to troubleshoot errors by granting you temporary access to the administrator dashboard until all issues get resolved. Usually, when a critical error occurs, the site administrator receives a recovery link through which you can access the WordPress dashboard. In case you don’t receive any WordPress email, enable recovery mode as described in the steps below.

1. Use the WordPress recovery link

    https://example.com/wp-login.php?action=entered_recovery_mode

   When prompted, enter your WordPress administrator username and password to access recovery mode.

   

2. In recovery mode, navigate to Tools on the main navigation menu.

3. Click Site Health from the drop-down list

4. View the present WordPress issues on the Status page

5. Fix each of the WordPress issues to avoid any additional errors, and verify that your Status changes to Good

   

How to fix the Establish a Database Connection WordPress Error

The establishing a database connection error is common and displays when WordPress is unable to write to the database using the user and password in your wp-config.php file. Usually, the database server can run into an error, or your user can't write to the WordPress database. Fix this error as described in the steps below.

1. Verify that the database server is up and running

    $ sudo systemctl status mysql

   Output:

    ● mariadb.service - MariaDB 10.11.4 database server
         Loaded: loaded (/lib/systemd/system/mariadb.service; enabled; vendor preset: enabled)
        Drop-In: /etc/systemd/system/mariadb.service.d
                 └─migrated-from-my.cnf-settings.conf
         Active: active (running) since Sat 2023-07-15 20:19:00 UTC; 1 month 15 days ago
           Docs: man:mariadbd(8)
                 https://mariadb.com/kb/en/library/systemd/
       Main PID: 25878 (mariadbd)
         Status: "Taking your SQL requests now..."

   If the Database server status is Inactive (Failed). Restart it to access all databases

    $ sudo systemctl restart mysql

   Verify that it runs correctly with any errors. If not, view the database logs to establish the source of the error

    $ sudo cat /var/log/mysql/error.log

   Output:

    2023-08-07T12:00:00.123456Z 0 [Note] InnoDB: Buffer pool(s) load completed at 210707 12:00:00
    2023-08-07T12:00:01.234567Z 0 [ERROR] mysqld: Out of memory (Needed 123456 bytes)
    2023-08-07T12:00:03.456789Z 0 [ERROR] Table 'mydatabase.mytable' doesn't exist
    2023-08-07T12:00:04.567890Z 0 [ERROR] Can't start server: Bind on TCP/IP port: Address already in

   As displayed in the above output, the MySQL database server is unable to start due to low server memory, and conflicts with another application on port 3306.

2. Verify the contents of your wp-config.php file

    $ cat /var/www/example.com/wp-config.php

   Output:

    /** The name of the database for WordPress */
    define( 'DB_NAME', 'wordpressdb' );
   
    /** MySQL database username */
    define( 'DB_USER', 'wpuser' );
   
    /** MySQL database password */
    define( 'DB_PASSWORD', 'strong-password' );
   
    /** MySQL hostname */
    define( 'DB_HOST', 'localhost' );
   
    /** Database Charset to use in creating database tables. */
    define( 'DB_CHARSET', 'utf8' );
   
    /** WordPress Database Table prefix. */
    $table_prefix = 'wp_';

   Verify that the database name, user, and password match with actual records on your MySQL database server. Also, take note of the $table_prefix = directive that should match your database naming style. To test your user access, log in to the MySQL database server.

    $ mysql -u wpuser -p

   When prompted, enter your password

   View the available databases, and verify that the WordPress database displays on the list

    > SHOW DATABASES;

   Switch to the database

    > USE wordpressdb;

   View the database tables and verify that the naming prefix matches your $table_prefix = value in the wp-config.php file

    > SHOW TABLES;

   Output:

    +----------------------------+
    | Tables_in_wordpressdb      |
    +----------------------------+
    | wp_actionscheduler_actions |
    | wp_actionscheduler_claims  |
    | wp_actionscheduler_groups  |
    | wp_actionscheduler_logs    |
    | wp_as3cf_items             |
    | wp_commentmeta             |
    | wp_comments                |
    | wp_e_events                |
    | wp_links                   |

   As displayed in the output, wp is the WordPress table prefix that should appear in your wp-config.php file

How to fix the Your Connection is Not Private (Invalid SSL Certificate) Error

When your WordPress server runs with an invalid SSL certificate, an Insecure Connection or Your Connection is not Private web browser error displays to every site visitor before your site loads. To correct this error, verify that your web server points to the correct SSL certificates. When using a free Let's Encrypt certificate, use the Certbot tool to renew or re-generate SSL certificates for your domain as described below.

1. Navigate to the web server virtual host files directory. For example /etc/nginx/sites-enabled

    $ cd /etc/nginx/sites-enabled/
   

2. View your WordPress host configuration file

    $ cat example.com

   When running multiple WordPress sites on the same web server, use the following command to identify your target configuration file. Replace example.com with your actual domain name

    $ grep -r "example.com" /etc/nginx/sites-enabled/
   

3. Verify that the ssl_certificate and ssl_certificate_key directives point to the /etc/letsencrypt/live/ directory

    # SSL certificate managed by Certbot
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
   

4. Using the certbot client tool, generate a new SSL certificate for your WordPress site. Replace example.com with your actual domain name.

    $ sudo certbot --nginx -d example.com

   Verify that the certificate issuance process is successful

5. Test that the certificate auto-renews upon expiry

    $ sudo certbot renew --dry-run

   Output:

    Saving debug log to /var/log/letsencrypt/letsencrypt.log
   
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Processing /etc/letsencrypt/renewal/example.com.conf
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Account registered.

   When successful, Certbot automatically renews your WordPress SSL certificate every 90 days.

6. In your web browser, visit your WordPress site to test HTTPS access, and verify that the Invalid SSL certificate error no longer displays to site visitors

    https://example.com

To implement different types of SSL certificates, visit the following resources:

• How to Choose an SSL/TLS Certificate: Commercial, Self-Signed, or Let's Encrypt
• Use Cloudflare and Vultr Firewall to Protect a Vultr Cloud Server
• Install Let's Encrypt SSL on Ubuntu with Apache or Nginx

How to fix the 503 Service Unavailable Error

The WordPress 503 Service unavailable error is commonly a result of resource limitations on your server. Usually, when your WordPress server hits your maximum allowed Bandwidth volume, the error displays as data requests do not complete successfully. Also, it can result from poorly coded plugins or theme files, fix the error as displayed in the steps below.

1. Log in to your WordPress server control panel, and verify your server has enough allocated bandwidth

   Depending on your hosting provider, unlimited bandwidth may display in your control panel, but when it's indirectly limited. If you identify bandwidth caps, migrate to a predictable pricing provider such as Vultr to scale your server to your needs

2. View your web server error logs and verify error source

    $ sudo cat /var/log/nginx/error.log
   

3. Verify that PHP-FPM is running correctly on your server to handle PHP scripts

    $ sudo systemctl status php-fpm

   Depending on your PHP version, you can rename to view the FPM status. For example php8.1-fpm

4. If the error persists, navigate to your wp-content directory

    $ cd /wp-content
   

5. Rename the directory to plugins_old

    $ mv plugins plugins_old

   Recreate the plugins directory and verify if the error gets resolved. If not, investigate the status of server infrastructure, web server, and WordPress error logs to find the exact source of the error.

How to fix the 404 Page Not Found Error

The HTTP 404 error displays when the web server is unable to find a requested resource on the server. For example, when the site visitor requests a file or page that's not available on the server, the web server returns the 404 error. Find and fix the error as described below.

1. Grant the web server ownership permissions to the WordPress web root directory

    $ sudo chown -R www-data:www-data /var/www/html/
   

2. Set the correct directory and file permissions

   755 directories:

    $ sudo find /var/www/html/ -type d -exec chmod 755 {} \;

   644 on files:

    $ sudo find /var/www/html/ -type f -exec chmod 644 {} \;
   

3. Long list the web root directory and verify the available permission values

    $ ls -l /var/www/html/

   Output:

    drwxr-xr-x  9 www-data www-data  4096 Aug  8 20:26 wp-admin
    -rw-r--r--  1 www-data www-data   351 May  9 03:17 wp-blog-header.php
    -rw-r--r--  1 www-data www-data  2323 Aug  8 20:26 wp-comments-post.php
    -rw-r--r--  1 www-data www-data  3360 Jul 27 14:42 wp-config.php
    -rw-r--r--  1 www-data www-data  3013 May  9 03:17 wp-config-sample.php
    drwxr-xr-x 10 www-data www-data  4096 Aug 27 20:53 wp-content
    -rw-r--r--  1 www-data www-data  5638 Aug  8 20:26 wp-cron.php
    drwxr-xr-x 27 www-data www-data 16384 Aug  8 20:26 wp-includes
    -rw-r--r--  1 www-data www-data  2502 May  9 03:17 wp-links-opml.php
    -rw-r--r--  1 www-data www-data  3927 Aug  8 20:26 wp-load.php
    -rw-r--r--  1 www-data www-data 49441 Aug  8 20:26 wp-login.php

   Revisit your WordPress site, verify that the requested resource is available on the server, and the error does not display again

4. View your WordPress web server configuration file

    $ sudo cat /etc/nginx/sites-enabled/example.com
   

5. Verify that the configuration points to the WordPress web root directory

    root /var/www/html;

   Depending on your web server, the web root directive may appear different. For example DocumentRoot when using Apache

6. Log in to your WordPress administrator dashboard

    https://example.com/wp-admin
   

7. Navigate to Settings > Permalinks, reset your WordPress Permalinks structure to refresh your URL structure and avoid 404 errors

How to fix the HTTP 500 Internal Server Error

1. Verify that the web server is up and running

    $ sudo systemctl status nginx
   

2. Verify that PHP-FPM is active and running

    $ sudo systemctl status php-fpm
   

3. View the web server error logs to verify the exact source of the error

    $ sudo cat /var/log/nginx/error.log
   

4. Also, view the PHP-FPM error logs to verify if the error is not caused by a PHP script

    $ sudo cat /var/log/php-fpm/error.log

   Output:

       2023/08/07 12:34:56 [error] 12345#0: *6789 FastCGI sent in stderr: "PHP message: PHP Fatal error:  Uncaught Error: Call to undefined function someUndefinedFunction() in /var/www/html/wp-content/custom-plugin.php:23
    Stack trace:
    #0 {main}
      thrown in /var/www/html/wp-content/custom-plugin.php on line 23" while reading response header from upstream, client: 192.168.1.1, server: example.com, request: "GET /page.php HTTP/1.1", upstream: "fastcgi://unix:/var/run/php/php7.4-fpm.sock:", host: "example.com", referrer: "http://example.com/"

How to Fix the 502 Bad Gateway Error

The HTTP 502 bad gateway error is results from a web server response time out. When a user makes a request to your WordPress site, the web server returns the 502 gateway error when it’s unable to handle the request. Usually, when the connection to PHP-FPM times out, the web server returns the error. Find the source of the error, and fix it as described below.

1. View the latest web server error log entries

    $ sudo cat /var/log/nginx/error.log | tail
   

2. Find the latest error. Usually, you may find the error *1 connect() to unix:/var/run/php-fpm.socket failed (2: No such file or directory) while connecting to upstream. To fix it, view your web server configuration

    $ cat /etc/nginx/sites-enabled/example.com
   

3. Verify that the correct PHP configurations are available in the /.php section

    location ~ \.php$ {
           include snippets/fastcgi-php.conf;
           fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    }
   

4. Verify that PHP-FPM (based on your version) is up and running

    $ sudo systemctl status php8.1-fpm

   Output:

    ● php8.1-fpm.service - The PHP 8.1 FastCGI Process Manager
         Loaded: loaded (/lib/systemd/system/php8.1-fpm.service; enabled; vendor preset: enabled)
         Active: active (running) since Wed 2023-08-30 17:55:55 UTC; 27s ago
   

5. If the error persists, view the PHP-FPM configuration

    $ cat /etc/php/8.1/fpm/pool.d/www.conf
   

6. Verify the user/group and verify that it runs as the web server user www-data

    ; Unix user/group of processes
    ; Note: The user is mandatory. If the group is not set, the default user's group
    ;       will be used.
    user = www-data
    group = www-data

Visit your WordPress site and verify that the error does not appear again. When it does, view your web server error logs again to verify the source of the error.

How to Fix the 403 Forbidden Error

HTTP 403 forbidden error displays due to improper permissions to access a specific resource on the WordPress server. Usually, if the web server does not have read privileges to a resource, the error displays on your WordPress site. Fix the error as described below.

1. View the web server error logs to find the exact source of the error

    $ sudo cat /var/log/nginx/error.log
   

2. Long list the WordPress web root directory and verify that the www-data user has read privileges

    $ ls -l /var/www/html/

   Output:

    drwxr-xr-x  9 www-data www-data  4096 Aug  8 20:26 wp-admin
    -rw-r--r--  1 www-data www-data   351 May  9 03:17 wp-blog-header.php
    -rw-r--r--  1 www-data www-data  2323 Aug  8 20:26 wp-comments-post.php
    -rw-r--r--  1 www-data www-data  3360 Jul 27 14:42 wp-config.php
    drwxr-xr-x 10 www-data www-data  4096 Aug 27 20:53 wp-content
    drwxr-xr-x 27 www-data www-data 16384 Aug  8 20:26 wp-includes

   Grant the www-data web server user full privileges to the directory

    $ sudo chown -R www-data:www-data /var/www/html/
   

3. Set the correct WordPress directory permissions

    $ sudo find /var/www/html/ -type d -exec chmod 755 {} \;
   

4. Set the correct WordPress file permissions

    $ sudo find /var/www/html/ -type f -exec chmod 644 {} \;
   

5. Visit your WordPress site and verify that the error does not display again

    https://example.com

How to Fix the Upload: Failed to Write File to Disk Error

When the web server is unable to write new files uploaded through your WordPress dashboard, the failed to write file to disk error displays. To fix the error, verify that the web server has read and write privileges to the WordPress web root directory. Verify the permissions as described below.

1. View the WordPress web root directory permissions

    $ ls -l /var/www/html/
   

2. Set the correct directory permissions

    $ sudo find /var/www/html/ -type d -exec chmod 755 {} \;
   

3. Set the WordPress file permissions

    $ sudo find /var/www/html/ -type f -exec chmod 644 {} \;

How To Fix This Site is Experiencing Technical Difficulties WordPress Error

When WordPress upgrades to the latest version, the site is experiencing technical difficulties error may display. This is because some themes or plugin files may be incompatible with the new upgrade, find the exact WordPress resource and fix the error as described below.

1. Rename the plugins directory to pluginsold

    $ sudo mv /var/www/html/wp-content/plugins /var/www/html/wp-content/pluginsold
   

2. Create a new plugins directory

    $ sudo mkdir /var/www/html/wp-content/plugins 
   

3. Visit your WordPress dashboard to activate the new plugins directory

    https://example.com/wp-admin
   

4. In your terminal session, copy the old plugins one by one. For example, start with woocommerce if available

    $ sudo cp /var/www/html/wp-content/plugins-old/woocommerce /var/www/html/wp-content/plugins 

   Depending on the number of available plugins, copy the most important plugins first, and the suspected plugins last

   

5. In your WordPress dashboard, reactivate the plugins one by one

6. If the error displays after activating a specific plugin, disable the plugin, and search for an updated version before reactivating it again.

   

7. In case the error is a result of a broken theme, verify that your active theme supports the latest WordPress version, if not, downgrade your WordPress to the most stable backed-up version

How to Fix the WordPress White Screen of Death (Blank Screen)

The WordPress white screen of death is a blank screen that displays no error, but does not accept any interactions on your WordPress site. Instead of a white screen, the error There has been a critical error on this website may display, both errors are the same and affect your general site performance. Usually, the error displays due to theme or plugin issues, and below are the recommended troubleshooting actions.

• Rename and Deactivate all WordPress Plugins. Then, reactivate them one by one
• Deactivate the WordPress theme and switch to the default theme
• Enable WordPress debugging and view the logs
• View the web server logs
• Increase the PHP memory limit
• Enter the WordPress recovery mode

For more information, visit Troubleshooting the WordPress White Screen of Death.

Conclusion

In this article, you implemented troubleshooting steps to fix common WordPress errors on your site. Among these, you implemented backend server actions that allow you to discover errors and work on them before they appear to your WordPress site visitors. For more information, visit the WordPress common errors page.