Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!


WordPress White Screen of Death

The White Screen of Death refers to any WordPress URL that loads completely blank. This generally means an error has occurred and is being hidden by WordPress.

To show the error messages add the following code to your wp-config.php directly after the line that reads:
error_reporting(E_ALL); ini_set('display_errors', 1);

In addition, add the following code above /* That's all, stop editing! Happy blogging. */ :

define( 'WP_DEBUG', true);

This will insure that error reporting is enabled before nearly anything else happens in WordPress. It will also insure that PHP is set to display errors in the browser window making it easier to find the error causing the problem. After determining the problem do not forget to remove the lines you just added to wp-config.php.

Another technique for displaying errors is to add the following line of code to the top of your .htaccess file

php_flag display_errors on

Remember to disable error messages from displaying when you are done debugging.

Determining the cause to 'Error establishing a database connection' or similar error

This error suggests WordPress cannot connect to your database. Check the below settings in your wp-config.php and verify they are correct:

  • Database name
  • username
  • password
  • host

The most common mistake is the wrong host. The host by default is set to localhost, but many hosting companies require a server name for this value. A typical search on any search engine like "wordpress [your webhosts name] host" will return an FAQ or forum article detailing where to find that information for your particular host.

There is also a MySQL connection and selection test script which can be retrieved from http://gist.github.com/162913.txt. copy the contents of that link into a file called wp-mysql-test.php and place it in the same directory as wp-config.php. It can be called from a web browser or executed from the command line.

Permalinks Not Working

If you just switched from the default permalink style of '/?p=123' to something like '/2009/07/14/sample-post/' and you are getting a 404 page not found error then these steps will likely help you. If you are not running your own server then it is likely that only step 1 will apply to you. If you are running your own server check all steps.

Step 1: Make sure your .htaccess file is created and written, and that the internal rewrites are up to date

The easiest way to determine if your .htaccess file is being written and created is to go to the admin of your site and navigate to Settings->Permalinks. If you switched back to the Default permalink style select a new permalink style and click 'Save Changes'. If you currently have a permalink style other than Default selected just click 'Save Changes'.

If you see a notice at the top of the screen under where it reads "Permalink Settings" that says "You should update your .htaccess now." you will need to scroll to the bottom of that page and copy the contents in the text area into a file called .htaccess and upload it to your website, placing it in the directory where WordPress is installed.

If this has not resolved your issue and you run your own server please continue to Step 2.

Step 2: Make sure that mod_rewrite is enabled in Apache


Begin by running the following command:

sudo a2enmod rewrite

If the module was just now enabled you should see a message stating:

Enabling module rewrite.
Run '/etc/init.d/apache2 restart' to activate new configuration!

If this is the message you see the proceed with running the following command:

sudo /etc/init.d/apache2 restart

If you see a message stating "Module rewrite already enabled" or enabling this module did not resolve the problem proceed to Step 3.

Fedora/Red Hat/CentOS

Begin by opening the global Apache configuration file in a text editor by running the following command:

nano /etc/httpd/conf/httpd.conf

Once this file is open look for the line reading:

LoadModule rewrite_module modules/mod_rewrite.so

If the line is preceeded by a # then remove that # and save the file. After making this change proceed to restart Apache using the following commands:

/etc/init.d/httpd restart

Note if you have sudo setup on your Fedora/Red Hat/CentOS install you can just run "sudo /etc/init.d/httpd restart".

If the module was already enabled or enabling it did not resolve the problem proceed to Step 3.

Step 3: Make sure that Apache is allowing you to use mod_rewrite in a .htaccess

If you set up a virtual host configuration for your WordPress install continue through this Step. Otherwise if you simply stuck the WordPress install in the default document root and things are still not working at this point you should head to the HTTPd IRC Channel on freenode.

Open the configuration file containing the <VirtualHost> Directive for your WordPress install and add the following lines:

<Directory /path/to/wordpress>
    AllowOverride All

This should make the full configuration look like: (simple example)

<VirtualHost *:80>
    ServerName example.org
    DocumentRoot /var/www/example.org
    <Directory /var/www/example.org>
        AllowOverride All

If you do not want to allow all types of .htaccess configurations use "AllowOverride FileInfo".

After making this modifications restart Apache using the methods outlines in Step 2.

I moved WordPress to a new domain without changing the domain settings first

The easiest way to fix this is add the following bit of code to your wp-config.php file above /* That's all, stop editing! Happy blogging. */

define('RELOCATE', true);

After making this modification navigate to your wp-login.php url (example: http://example.org/wordpress/wp-login.php). Do not go to /wp-admin/ as this will attempt to redirect you to the url stored in the database which is incorrect.

After successfully logging in go to Settings->General and update the "Blog address (URL)" field with the correct information.

Do not forget to remove the code added to wp-config.php.

WordPress version X was just released and I am not receiving an update message or I have just updated and am still seeing this message

In either case the solution is the same. If a new version was just released and you are not seeing the update now message than don't worry. WordPress only checks once every 12 hours for updates. So it will likely just take a while. If you want to force the update check continue on.

In WordPress 2.8 or newer use the following MySQL command:

DELETE FROM wp_options WHERE option_name='_transient_update_core';

In WordPress versions older than 2.8 use:

SELECT FROM wp_options WHERE option_name='update_core';

Uploads do not work after pushing my local install to my server

This is usually caused by the full file system path to the uploads directory being stored in the database. The quick fix is to navigate to Settings->Miscellaneous, verify the upload path only reads "wp-content/uploads" and then click save changes.

I activated a theme and now cannot access the frontend or admin of my site

There are a couple SQL commands that you can run to switch the settings back to the default theme shipped with WordPress. Be careful to use the correct steps based on your WordPress version:

Versions 2.9.x and older

UPDATE wp_options SET option_value='default' WHERE option_name IN ('template', 'stylesheet');
UPDATE wp_options SET option_value='WordPress Default' WHERE option_name='current_theme';

Version 3.0.x, 3.1.x, 3.2.x

UPDATE wp_options SET option_value='twentyten' WHERE option_name IN ('template', 'stylesheet');
UPDATE wp_options SET option_value='Twenty Ten' WHERE option_name='current_theme';

Version 3.3.x, 3.4.x

UPDATE wp_options SET option_value='twentyeleven' WHERE option_name IN ('template', 'stylesheet');
UPDATE wp_options SET option_value='Twenty Eleven' WHERE option_name='current_theme';

Version 3.5.x

UPDATE wp_options SET option_value='twentytwelve' WHERE option_name IN ('template', 'stylesheet');
UPDATE wp_options SET option_value='Twenty Twelve' WHERE option_name='current_theme';