WordPress Permalinks 404 when Running in OS X

February 4th, 2010

I’m a designer here at Transmogrify (read: not a developer) and therefore close to none of what I’m about to write makes sense to me. I have, however, just solved a problem that’s been giving me trouble for a few hours now, and wanted to share it.

I installed WordPress on my MacBook Pro so that I could do a build-out of a site without needing to have hosting set up yet. Luckily, (Snow) Leopard has Apache and PHP support preinstalled, and the WordPress setup went off without a hitch (which was pretty impressive).

PHP has to be put into this folder by default for it to run on your machine: /Library/WebServer/Documents/

I’m sure there’s some way to change that, but it’s over my head. You can put things into subfolders in that folder though, and my install of WordPress is running from /Library/WebServer/Documents/wordpress/ (this is important to note for later). To view the site, I just need to go to http://localhost/wordpress/ in a browser.

I cleared my theme and started building the design from scratch when I remembered that I hadn’t yet set up “pretty” permalinks. The site is going to be page driven, with no posts, so I wanted to use this approach for links:

Which would make links that (eventually) look like this: www.website.com/contact.

After a little searching, I found some pointers from others with similar problems and followed their instructions. What I did was as follows:

1. Created an .htaccess file and dropped it into the main WordPress folder. I made that file in TextEdit, and saved it to /Library/WebServer/Documents/wordpress/. In order to see that file though, I needed to show hidden files in the Finder. To do that, I opened the Terminal and ran this:

defaults write com.apple.Finder AppleShowAllFiles TRUE

and then restarted the Finder in Terminal:

KillAll Finder

(Note: To hide hidden files again, just run this again but change TRUE to FALSE.)

2. I set permissions on the .htaccess so that it’s writable by WordPress. The easiest way to do this is to get info (command + i) on the newly created and unhidden .htaccess file in Finder, and change all of the settings under Sharing & Permissions to “Read & Write.” There’s also a nice tool for changing file permissions in a more FTP client-like way, called BatChmod. The most “natural” way is to do this via the Terminal, but I’m more of a GUI type of person. Here’s what the Get Info screen looks like:

After all of that, I thought I was good. I went to the Permalinks settings in the WordPress Admin and set up my custom URLs. Unfortunately, any time I changed the Permalink settings from the default setting to anything else, all of my links would change but the pages would 404. This is where the real fun started.

More searching ensued, and I stumbled onto the idea that httpd.conf (an Apache configuration file) needed to be edited to allow your .htaccess to rewrite URLs. I found this information on WordPress forum threads and blog posts like this, this, and this. Though some of these suggestions may help you solve your problems, I was still faced with a dreaded 404 error on every page.

Those posts all pointed me to /private/etc/apache2/httpd.conf, but what I found is that the real file that needed to be fixed was here: /private/etc/apache2/users/myusername.conf. Here’s what I needed to do:

1. Opened /private/etc/apache2/myusername.conf in a text editor.

It looked like this:

3. Copied that chunk of code and pasted it again below it. So it looks like this:

4. Changed the Directory and the AllowOverride settings on the second entry so that all together it looked like this:

Remember when I said the location of your WordPress install was important? This is the directory you need to enter here. The problem wasn’t that the .htaccess wasn’t creating the right links, it was that Apache wasn’t being pointed to that directory to find the .htaccess file. This was the key to getting it all working.

5. Restarted Apache. The easiest way to do that is by going into the Sharing preference pane and turning “Web Sharing” off and turning it back on again.

And finally, I had nice URLs!

It’s probably a good idea to hide all of those hidden files again at this point.