Smart 404 for WordPress

Save visitors to your WordPress site from unhelpful 404 errors!

When a page cannot be found, Smart 404 will use the current URL to attempt to find a matching page, and redirect to it automatically. Smart 404 also supplies template tags which provide a list of suggestions, for use on a 404.php template page if a matching post can’t be immediately discovered.

Instead of quickly giving up when a visitor reaches a page that doesn’t exist, make an effort to guess what they were after in the first place. This plugin will perform a search of your posts, tags and categories, using keywords from the requested URL. If there’s a match, redirect to that page instead of showing the error. If there’s more than one match, the 404 template can use some template tags to provide a list of suggestions to the visitor.

This plugin is also useful if you have recently changed your permalink structure: With minimal or no adjustment, old permalinks will still work.

My latest project:

The Cartographer banner


Get Smart 404 over at the Smart 404 WordPress Plugin page!


  1. Unzip the package, and upload smart404 to the /wp-content/plugins/ directory on your WordPress site.
  2. Activate the plugin through the ‘Plugins’ menu in WordPress.
  3. Optionally, alter your theme’s 404.php template to list suggestions from Smart 404

Note: If you desire reporting on 404 errors that Smart 404 is unable to remedy, I recommend Joe Hoyle’s JH 404 Logger, which adds an item to your dashboard listing 404 errors. 404 Notifier by Alex King will send emails for 404 errors, but I hear reports that emails are sent for 404 errors that this plugin is able to recover from, not just unrecoverable errors.


There are two configuration options for Smart 404:


Turn on or off searching of posts, pages, tags and categories

Ignored patterns

A newline-separated list of terms or patterns to ignore from the URL. This is particularly useful for supporting old permalinks with an ID number in them. For example, to work with URLs like:


Add the regular expression pattern:


This will ignore all numbers, followed by a hyphen, at the start of the URL.

Template Configuration

To provide a helpful list of suggested posts in your 404 pages, modify the 404.php template in your theme to use a Smart 404 template tag. For example:

<?php if (smart404_has_suggestions()) : ?>
Try one of these links:
<?php smart404_suggestions(); ?>
<?php endif; ?>

Or, for something a little more complicated:

<?php if (smart404_loop()) : ?>
<p>Or, try one of these posts:</p>
<?php while (have_posts()) : the_post(); ?>
<h4><a href="<?php the_permalink() ?>"
title="<?php the_title_attribute(); ?>">
<?php the_title(); ?></a></h4>
  <small><?php the_excerpt(); ?></small>
<?php endwhile; ?>
<?php endif; ?>

Note that smart404_loop() will only work for posts, not pages, due to limitations in the loop mechanism. Several template tags are supplied by Smart 404 for use in the 404.php template:


Returns true if there are some suggestions, false otherwise


Retrieve an array of post objects for rendering manually.


Draw a list of suggested posts.

Pass the parameter “list” to render suggestions as a list.


Query posts for use in a Loop. See the second example above for usage. Note that smart404_loop() will only work for posts, not pages, due to limitations in the loop mechanism.

, , , . Bookmark the permalink. Both comments and trackbacks are currently closed.


  1. Posted November 14, 2010 at 2:07 am | Permalink

    I was having some unicode type problems and this fixed URLs that showed up like this:



    But if the messed up part is in the middle of the URL, then it does not seem to work, so for something like this:


    I tried fixing this in htaccess but then figured out that the page URL was being passed to WP (and subsequently giving me a 404 page with my site’s theme), so I figured the fix had to be with a WP plugin. This plugin has come the closest so far – fixing one page but not fixing the remaining 4. This: “%E2%80%8” seems to be in each URL. Any ideas?

  2. Posted November 15, 2010 at 10:48 pm | Permalink


    It saved me after changing permalinks structure. A huuuuge thank you!

  3. Posted November 16, 2010 at 7:19 am | Permalink

    hi. i use your plug in in this site: and sure it was helpfull

  4. Posted November 22, 2010 at 12:00 am | Permalink

    Hi, thanks for a very useful plugin! I just shifted a blog, and there were 404s galore. You’re plugin worked instantly, no need to do anything.

    I do have a question though, regarding HOW it redirects. Does it place a 302 or 301 redirect?

    • Posted November 22, 2010 at 10:07 am | Permalink

      Great, glad to hear it works for you!

      It does a 301 redirect, but if you need a 302, you can modify smart-404.php and change the 301s.

      • Posted November 22, 2010 at 12:13 pm | Permalink

        Thats excellent, thanks once again Michael. I need 301s in this case. One suggestion for the plugin – perhaps it could offer the ability to switch between 301s or 302s within the plugin (ie admin backend), although as you suggested, modifying the php file shouldn’t be too difficult for anyone even slightly comfortable with coding.

  5. Michael
    Posted November 27, 2010 at 6:31 pm | Permalink

    Thank you for this great plugin, it saved me a lot of time.

    Just one note, I was dealing with old site that had .htm extension so I added this in your code on line 55 $patterns_array[] = “\.(html|htm|php)$”; and now everything works perfectly. Maybe someone else will have the same problem.


  6. Posted December 3, 2010 at 7:12 pm | Permalink

    This plugin is great except for one thing: it breaks all my references to page numbers.

    Normally, I can link to a particular page with something like “index.php?p=305”. That’s a common WordPress tactic.

    However, with this plugin installed, all my “index.php?” links are broken. Is there a way for me to ignore that?


  7. Posted January 8, 2011 at 2:49 pm | Permalink

    Thank you very much for this. I use it on one of my sites, example:

    Had to figure out myself how to do some automatic text-only post excerpts with PHP because WordPress doesn’t give excerpts of my pages. :( Anyway I’m very happy with the result. :)

  8. Posted February 4, 2011 at 3:35 pm | Permalink

    Very good Plugin … I use it in my site:, very good results.

  9. Posted February 4, 2011 at 6:05 pm | Permalink

    There is a way to integrate this with the WP search, I’m using another plug in for searches and get better search results using it.

  10. Posted February 22, 2011 at 7:43 pm | Permalink

    Do we have any way to get the “purified” word list that the plugin searches for? :-)

    • Posted February 22, 2011 at 8:11 pm | Permalink

      Is the smart404_get_search_terms function what you’re looking for?:

      Retrieve an array of search terms used to populate the suggestions list, for use with contextual highlighting, etc.

      • Posted February 22, 2011 at 8:22 pm | Permalink

        Awesome! :) Now with a help from a JSON created with and a bit of string manipulation I can add search results from my bbPress forum. ;)

  11. Posted February 28, 2011 at 1:29 pm | Permalink

    Very nice plugin! I think it would be a nice feature if the title-Tag (maybe description and keywords too) could be searched too. Thanx for this plugin!

  12. Shelly
    Posted March 11, 2011 at 5:26 pm | Permalink

    How about custom post types and registered taxonomies? Plugin is working great (much better than my old method of pulling this off), but it’s only returning regular posts, categories and tags – it seems to be ignoring my registered (non-standard) custom taxonomies and custom post types. I’m messing around in the PHP file at the moment, but still not getting the results I’d like.

    • Shelly
      Posted March 11, 2011 at 5:30 pm | Permalink

      Gar. Scratch that. I guess what I did is working! I had to manually add in my custom stuff though. I basically added new info to the case/break sections, but I had to manually type in the names of my custom tags, custom categories and custom post types to make it recognize them. Might be nicer to add some kind of field where you can type in the names of the registered custom stuff, or just have it automatically detect anything that’s not “of the norm”. but it’s working fine! I guess I spoke too soon :)

  13. Posted March 14, 2011 at 2:35 pm | Permalink

    Great plugin, very useful! ThoughI had an issue after moving over to blogger due to my site having urls as post titles, for instance I had com.html last part of the URL, I fixed it by:

    Finding around line 55: $patterns_array[] = "\.(html|php)$";

    Replace with:

    $patterns_array[] = "com\.(html|php)$";

    • Posted March 14, 2011 at 7:04 pm | Permalink

      Actually, the plugin has a configuration option for this, in settings – just add the line “com.html”

  14. Posted March 19, 2011 at 2:57 pm | Permalink

    Hello, I want to thank you for your work about plugin for wordpress. So I thought to name your work and your website in may network page.

    I hope you are happy for this. Many thanks Pietro

  15. Posted April 1, 2011 at 1:08 am | Permalink

    This is completely awesome!!! I have used it for almost two years now, and whenever I need to reference something I wrote about, I just type a keyword after the blog’s URL to get the page that I need! It’s super handy if I have to remember some code or quote something.

  16. Posted April 14, 2011 at 5:18 pm | Permalink

    Smart 404 are smart, but why does you not use on your own homepage?…

  17. Posted April 22, 2011 at 5:25 pm | Permalink


    great addon, i use it on my site – it works if i use part of the url only. But if i try it with a typo in the middle than im dropped to the 404 page. I added the smart404_loop to my 404.php but i dont get a list of matching posts. Im wondering if i do something wrong.

    Thanks Mike

  18. Posted May 2, 2011 at 5:50 pm | Permalink

    thanks I had a jobs blog and often I have to delete posts for jobs that are expired so i was looking for a plugin that could allow me easy customization of 404.

  19. Posted May 15, 2011 at 9:43 pm | Permalink

    i used your plugin in my blog and it works like charm.

    thank you.

  20. Posted May 27, 2011 at 9:25 pm | Permalink

    Hi there,

    I’m having problems with it, hope you might give me a clue as to what to do!

    I’m using WordPress 3.1.3 I’ve got your plugin 0.5 active (and unticked tags and categories in the options) I’ve pasted your simple code above in to the 404.php of my child theme (Child of twentyten)

    I know that the correct 404.php is being used cos I also changed some of the text in it, but the code doesn’t render any html.

    From the UK I google: westbury baptist youth work and follow the link to (which no longer exists) but just get my custom 404 without any smart suggestions. If you chuck those 4 keywords in to the wordpress search box on the 404 page a load of suggestions appear.

    Any clues what went wrong?



  21. Posted July 1, 2011 at 10:46 pm | Permalink

    Great plugin. However, it seems to have slowed down my website to a crawl. If I unintall it the website goes back to normal; if it is installed it can take a minute to go from page to page. Any ideas? Thanks. I am using the latest WordPress and Thesis 6.1.

  22. Posted July 17, 2011 at 3:19 am | Permalink

    Since updating to wordpress 3.2 the plugin has stopped working. Is there a known compatibility issue?

  23. Nathaniel
    Posted July 20, 2011 at 10:16 am | Permalink


    I’m having trouble displaying the list, I’m using this code (with and without ‘list’;

    Try one of these links:

    The redirect works well, I just can’t get it to display the list like others! Is this the correct code to display the list?


  24. Posted September 8, 2011 at 4:00 pm | Permalink

    Hi. I use your plug in in this site: It works. Thanks a lot

  25. jason
    Posted October 1, 2011 at 9:20 pm | Permalink

    every time i try to use this doesnt work..i even try to display the suggestions.. and nothing shows :(

  26. Posted November 24, 2011 at 5:17 pm | Permalink

    Seems like an depreciated function somewhere?

    has_cap was called with an argument that is deprecated since version 2.0! Usage of user levels by plugins and themes is deprecated. Use roles and capabilities instead.

  27. Posted November 26, 2011 at 1:39 pm | Permalink

    hi, is this plugin still alive?

    • Posted November 27, 2011 at 12:49 pm | Permalink

      It works for most people, Sibudi, although I don’t currently have the time to really actively maintain it or assist with setup.

  28. Posted November 28, 2011 at 2:08 am | Permalink

    Hey Michael,

    Thanks for Smart 404; it’s awesome. However, I’m having a small problem with it causing redirect loops, described here.

    Any suggestions?

    Thanks, Graham

    • Posted December 11, 2011 at 3:19 pm | Permalink

      i also see this behavior, but it’s not a problem on my website: my links are of the …/page/2 form:-)

  29. Robert
    Posted December 4, 2011 at 9:30 pm | Permalink


    I see my theme doesn’t have a 404.php file. Do I just create one with the code provided above, or do I need to add more code to it?



  30. Posted December 11, 2011 at 3:15 pm | Permalink

    i’m trying to use the results of smart404_get_search_terms, but i note that it only returns the tail of a 404: /vvv/yyy/zzz only returns zzz.

    and it seems to use only the – & _ chars as delimiters: /vvv-yyy returns vvv, yyy but /vvv.yyy returns vvv.yyy

    anybody dug into the code yet to see if these can be extended?