Skip to content

Category: WordPress

  • WordPress 404 Fix: Why You Just Need to “Resave” Your Permalinks

    If you’ve ever moved a WordPress site, updated a major plugin, or added a Custom Post Type, you’ve probably encountered the dreaded “404 Not Found” error on pages that you know exist.

    And if you’ve searched for the fix, you know the most common, and seemingly illogical, solution: Go to Settings > Permalinks and simply click “Save Changes,” without actually changing anything.

    Why does this magic button press work? It’s not magic; it’s a necessary synchronization between WordPress and your web server. Here is a history of the issue, a simple explanation of why it happens, and how to fix it for good.


    Part 1: The Core Problem—A Mismatch in Maps

    To understand the fix, you first have to understand the job of a permalink.

    Permalinks: The Simple Address

    A “permalink” is just the permanent, clean, and readable URL (like /my-awesome-post/). When a visitor types this into their browser, two main things have to happen:

    1. The Server’s Job (Nginx/Apache): The server has to receive the request and figure out that the clean-looking URL actually needs to be processed by one specific file: the main WordPress script (usually `index.php).
    2. WordPress’s Job: Once WordPress takes the request, it looks at its internal rules to determine exactly whichpiece of content (Post ID 123, Custom Post Type “Sponsored Content”, etc.) matches the URL.

    The technical glue that makes step 1 work is a set of instructions called Rewrite Rules.

    The History of the Problem

    When WordPress was first developed, the default URLs were ugly, using IDs and question marks (e.g., ?p=123). As websites became more advanced and SEO became critical, WordPress needed a clean URL structure.

    The permalink feature was created to solve this. It allowed WordPress to generate those complex Rewrite Rulesautomatically. The problem that has persisted is that WordPress is not always perfect at telling the web server or its own database that a new rule is needed.

    This is where the mismatch happens:

    • WordPress knows the page exists.
    • The Server’s Routing Map (the Rewrite Rules) is either missing the rule or using an outdated version.

    Part 2: The Role of Custom Post Type Plugins

    While WordPress core sometimes causes these issues, they are far more common when using third-party tools to create custom content structures.

    Plugins like WCK (WordPress Creation Kit)Custom Post Type UI, or similar builders are fantastic for easily adding new content types (like “Sponsored Content,” “Case Studies,” or “Products”) without writing code.

    However, they introduce an additional step in the communication chain:

    The ActionThe Expected ResultThe Potential Breakdown
    You create a new CPTThe CPT Plugin tells WordPress to register a new route.The plugin fails to send the final signal to save the updated Master Route List.
    You edit a CPT slugThe plugin updates the page, but doesn’t touch the routes.WordPress core doesn’t get the signal to check the routes, and the new URL is stuck in limbo.

    This creates a communication gap. The plugin is being “too efficient”—it only updates the content, not the site-wide map. The result is the same: the server looks at the old, incomplete map and throws a 404 Not Found error.


    Part 3: Why the “Save Changes” Button Works

    When you click “Save Changes” on the Permalinks screen, you are performing a critical synchronization step known as “Flushing the Rewrite Rules.”

    Think of your website as a Librarian (WordPress) with a Master Catalog (the Database).

    The Fix (Why it Works)

    By clicking the “Save Changes” button, even if you change nothing, you are essentially bypassing the complex, multi-layered system and giving WordPress this simple, non-negotiable command:

    “Discard the current, potentially stale Rewrite Rules, recalculate the entire list from scratch based on everything I have—all my posts, pages, and custom types—and then force that fresh list into the database and server configuration.”

    This simple action forces synchronization and instantly corrects the outdated routing map, clearing up the 404 errors caused by core glitches or plugin communication issues.


    Part 4: The Troubleshooting Steps

    The “resave” trick works over 90% of the time. If it doesn’t, here are the next steps to ensure the fix is permanent.

    1. The Standard Permalink Fix (The First Step)

    1. Navigate to Settings > Permalinks in your WordPress dashboard.
    2. Note your current setting (e.g., “Post Name”).
    3. Click the Save Changes button.

    2. The Cache Flush (The Second Step)

    Sometimes the fix works, but your visitors (or you) are seeing an older version of the site saved by a caching system.

    • Clear all forms of caching on your site: Server-level cache, WordPress plugin cache (WP Rocket, LiteSpeed, etc.), and CDN cache (Cloudflare, etc.).

    3. The Plugin Conflict Check (The Root Cause)

    If you find you have to resave permalinks constantly, the CPT plugin itself might be the conflict point.

    1. Deactivate all plugins except the one causing the issue (e.g., your CPT builder).
    2. Try to reproduce the 404 error (e.g., by changing a page slug).
    3. If the error stops, reactivate your plugins one by one, checking for the 404 each time, until you isolate the offender.

    By understanding that this is simply a synchronization error, often exacerbated by the tools we use for efficiency, you can confidently explain the “magic” of the resave button and troubleshoot any future routing headaches.

  • Say Goodbye to chown: Fixing WordPress File Permissions in Docker on Windows with WSL

    Say Goodbye to chown: Fixing WordPress File Permissions in Docker on Windows with WSL

    If you’re developing WordPress themes or plugins locally on Windows using Docker inside of WSL, you’ve likely run into a frustrating and time-consuming problem: the constant battle with file permissions.

    One minute, you need to set your theme files to adam:adam so you can edit them in your IDE like PhpStorm or VS Code. The next, you need to switch them to www-data:www-data so that the web server can run a server-side process, like an automatic SCSS compiler. Then, to update a plugin from the WordPress admin panel, you have to switch the permissions back again.

    This constant chown shuffle is a major drag on productivity. I recently faced this exact scenario with a specific local development stack:

    • Host OS: Windows 11
    • Linux Environment: WSL (Ubuntu)
    • Containerization: Docker Desktop
    • WordPress Image: The official wordpress:latest
    • Workflow: WordPress files mounted from my local WSL filesystem into the container.

    The goal was simple: edit files as my local user while allowing the WordPress container to perform its necessary file operations without constant permission changes. After some trial and error, I landed on a clean, permanent solution. This fix has been tested for the environment above and works perfectly.

    The Core of the Problem: A User ID Mismatch

    The friction comes from a fundamental conflict between users. On your WSL instance, your user (adam in my case) owns the project files. This user has a specific User ID (UID) and Group ID (GID), which are typically 1000 and 1000 for the default user on most Linux distributions.

    However, inside the official wordpress:latest Docker container, the Apache web server runs as the www-data user by default. This www-data user has a different UID and GID (usually 33). When WordPress needs to write a file—like scssphp compiling a stylesheet or a plugin being updated—it does so as www-data. Since the UIDs don’t match, you get permission errors unless you manually change the file owner to www-data.

    Worse yet, I noticed that on some occasions, a process would create a file owned by root, adding yet another layer of complexity. The solution is to stop juggling users and just make them the same.

    The Solution: Synchronize Your User with the Container

    The most robust fix is to tell Docker to run the Apache process inside the container using your own user’s UID and GID. This way, from the file system’s perspective, your local user and the web server user are identical. Any file you create can be read/written by the server, and any file the server creates is owned by you.

    Here’s how to do it in two simple steps.

    Step 1: Find Your User and Group ID in WSL

    First, you need to find the UID and GID of your user inside your WSL terminal. It’s almost certainly 1000:1000, but it’s always best to verify.

    Open your WSL terminal and run the following command:

    Bash

    id -u && id -g
    

    This will print your UID and GID. Take note of these numbers.

    Step 2: Update Your docker-compose.yml

    Next, open the docker-compose.yml file in your project root. We are going to add a single, powerful directive to your WordPress service configuration: user.

    Find the service definition for your WordPress container and add the line user: "1000:1000", replacing 1000:1000 with your actual UID and GID if they are different.

    Here is a before-and-after example:

    Before:

    YAML

    version: '3.8'
    services:
      wordpress:
        image: wordpress:latest
        volumes:
          - ./wp-content:/var/www/html/wp-content
          # other configurations...
        ports:
          - "8080:80"
        restart: always
    

    After:

    YAML

    version: '3.8'
    services:
      wordpress:
        image: wordpress:latest
        user: "1000:1000" # Add this line!
        volumes:
          - ./wp-content:/var/www/html/wp-content
          # other configurations...
        ports:
          - "8080:80"
        restart: always
    

    Step 3: Rebuild and Verify

    Save your docker-compose.yml file. Now, stop and rebuild your container to apply the change. Run this command from your project directory in the WSL terminal:

    Bash

    docker-compose down && docker-compose up -d --build
    

    Once the container is running, you can verify that it’s working. Have WordPress perform an action that creates a file. In my case, I deleted my old compiled CSS file and reloaded a page, which triggered the scssphp compiler.

    Then, check the file’s ownership in your terminal:

    Bash

    ls -l wp-content/themes/your-theme/path/to/main.css
    

    The owner should now be your local user (adam adam). Success! You can now edit the file, and the server can still overwrite it when it recompiles, with zero permission conflicts.

    A Smoother Path Forward

    By synchronizing the container’s user with your local user, you eliminate the source of the permission conflict entirely. This simple, one-line change to your docker-compose.yml creates a seamless and efficient local development workflow. No more context switching, no more running chown—just smooth, productive coding.

    Disclaimer: This solution has been specifically tested and confirmed to work with a development environment running on Windows, using Docker Desktop with the WSL backend, and running the official wordpress:latest image with locally mounted files. While the principles apply more broadly, the exact implementation may differ in other environments.

  • I published an accessibility plugin called Open Accessibility!

    Within the last couple of months, I was updating plugins for one of my employer’s WordPress sites. The accessibility plugin that I had been using and that had been an incredibly popular plugin had been called One Click Accessibility. There was a major version update from 2.x to 3 and when I installed it, I was met with a wildly different plugin. Long story short, the plugin was sold to Elementor and then went commercial.

    This really, really pissed me off. I could have just stayed on version 2 of the plugin perpetually but so many other people got screwed as well. There are many other accessibility plugins available in the WordPress plugin repository but I decided to make my own out of spite.

    Accessibility platforms like UserWay and Accessibe are prevalent and big business but while they will give you a widget or something to add to your site to assist those who need with things like text size, color contrast and the like, what they are selling is a “cover your ass” service in the even that you get sued. They aren’t marketing a product to help people, they are selling fear and then a handy peace of mind solution to those who think they need it.

    I don’t know, I have a fundamental problem with making money directly or indirectly from people who have a disability or who are differently-abled. The argument can be made that commercial accessibility offerings aren’t protecting site owners from people with disabilities but rather the trolls that will sue anyone for anything and then offer a settlement to make a quick, shitty buck. Those people exist and they suck but site owners that genuinely give a shit about their users should have options a-plenty.

    The project was always intended to be open source and while it can’t provide any type of legal services, it can at least help make the best effort possible to accommodate all type of different use cases for people with different needs.

    You can find my official plugin here. This project is (and will always be) open source and my GitHub repo can be forked if you want to make it your own. I plan to actively work on this and incorporate feedback as well as new features so please let me know what you think and what you might want to see!

    By the way, I am using the plugin on this site so you can take it for a test drive and see if you think it could work for you and your sites.

  • Set Tag Order WordPress Plugin

    A few months ago, I was asked to solve what I thought was a simple problem. The question was, “Can we set the display order of tags?” It seemed like a very benign question until I started to dig into it and discovered that it’s, in fact, not a simple question at all. WordPress, by default, sorts tags alphabetically when you use the get_tags() function.

    The problem I was asked to create a solution for was to allow the editor to specify the order that tags are rendered on the corresponding post page. It was way more involed thatn I had anticipated but ultimately, I created a plugin that works with both the block editor and classic editor and should also work with any theme that displays tags using the get_tags() function.

    I’ve attached some screenshots to help illustrate but the plugin can be downloaded directly from my GitHub. I have made this public and welcome any and all feedback or feature requests!

    This plugin is now also listed in the WordPress plugin directory! You can download it from WordPress.org here or add it directly from your WordPress installation.

  • Out With Ghost, In With WordPress

    As much as using WordPress is cliche, my current job revolves around WordPress so it seemed fitting to use it personally as well. I had been using Ghost since I had been fully immersed in NodeJS, Next, React and researching any ‘new hotness’ JS frameworks or libraries that seemed to materialize out of thin air every few days.

    I like Ghost and it did everything I wanted and was very easy to set up and maintain on my Raspberry Pi web server. I appreciated not having to use plugins for features that WordPress should have built into the core long ago. I really appreciated the content editor which was very fast, and had all of the content editing and layout features I wanted. The templating engine was a bit of a learning curve but once I looked at some different themes and poked around under the hood, I was able to figure out how to get the frontend to do what I wanted it to do.

    Having been a PHP person for almost my entire professional career, WordPress was always looming over my shoulder. When I started to delve deep into NodeJS and other JavaScript or TypeScript-based frameworks, using Ghost for my own site seemed befitting. It was easy enough to set up and self-host on a Raspberry Pi so that’s what I did.

    Alas, I find myself fully immersed in WordPress on a daily basis. I wouldn’t have considered myself a WordPress developer before but I certainly would now. In less than a year’s time, I’ve learned sooooooo much about what WordPress can do and some quirks and shortcomings about what it can’t. As much as I want to be one of the cool kids running a JavaScript-based thing for my own site, it makes more sense to use WordPress and use it as a playground of sorts to experiment and get weird if I feel like it.

    Just like the answer to every car question is “Miata”, the answer to every website platform question is “WordPress”…

  • Reset WordPress Password Directly in Database

    My current job has found me in a sea of WordPress sites. Since we don’t allow (or want, at this time) users to register, the PHP mail() function is not enabled along with the security risks that PHP mail(); brings along with it. So what happens when a user needs their password reset? Currently, an admin has to manually set a new password. That’s fine and dandy but what happens if you only have one admin account and you’re locked out?

    The answer to that question is simple – reset the password directly in the database. Before you do that however, the new password needs hashed. You can use a simple MD5 hash to insert into your database which WordPress will run through its own wordpress_generate_password() function to create the proper form or you can use this tool that I built in order to create a ready-to-go WordPress password hash and example SQL query to run against your target database.

    Once you’ve got your hash, go into your WordPress database, and then find the ‘wp_users’ table. Inside of that table is a column called ‘user_pass’ – this is the field to enter your hash into.

    Execute the following SQL command (adjusted for your specific parameters):

    UPDATE wordpress.wp_users t SET t.user_pass = 'your-generated-hash' WHERE t.ID = 1;

    Replace “wordpress” with your database name and make sure you have the correct ID if you have multiple users otherwise, someone else is getting a new password.

    This can also be handy when installing WordPress within MAMP or MAMP Pro. I’ve found that in verisons 5 and 6 of MAMP Pro, when adding WordPress as an extra, the password you enter before MAMP installs WordPress never works. So, I’ve used this method to fix several WordPress installs when done through MAMP.

  • Replace Your Old Site URL with a New Site URL In Your WordPress Database

    I use the following SQL queries regularly to move databases between local, staging and development environments in my current role and have found them to be invaluable. There are plugins that can do this but a simple SQL query is going to be faster and the output from the SQL console will give you clear and concise feedback when executing. The following WordPress database queries are my “Swiss army knife” of tools when migrating databases across environments.

    First, to replace the Site Address (URL) and the WordPress Address (URL), use this query:

    UPDATE wp_options SET option_value = replace(option_value, 'http://www.your-old-domain.com', 'http://www.your-new-domain.com') WHERE option_name = 'home' OR option_name = 'siteurl';

    After that, we need to replace the URL’s contained within your post content, which is stored in the “post_content” column contained in the “wp_posts” table. To do that, use this query:

    UPDATE wp_posts SET post_content = replace(post_content, 'http://www.your-old-domain.com', 'http://www.your-new-domain.com');

    while we’re at it, we’ll also update instance of the old URL in the “guid” column. We’ll do that like this:

    UPDATE wp_posts SET guid = replace(guid, 'https://www.your-old-domain.com', 'http://www.your-new-domain.com');

    Your site will almost certainly work perfectly fine if you don’t update the “guid” column but if you rely on RSS then your feed will malfunction. Each guid is also a valid URL and each URL contained in the “guid” column will redirect you to the corresponding post so while this may not seem like a big deal if nothing is obviously broken, it is a significant piece in the overall health and proper function of your site.

    It’s also important to not overlook the “wp_postmeta” table. This table stores all of the data related to each post in your site. Any hardcoded instances of your old site URL can have a negative affect on the functionality of your site. To update the post meta_value, use this query:

    UPDATE wp_postmeta SET meta_value = replace(meta_value, 'http://www.your-old-domain.com', 'http://www.your-new-domain.com');

    Last, and this only applies if you use or have used the comments feature, is that we need to replace the URL’s in any comments made on your site. Top do that, use this query:

    UPDATE wp_comments SET comment_content = replace(comment_content , 'http://www.your-old-domain.com', 'http://www.your-new-domain.com');

    When the queries run successfully, you should see an output like the following:

    Query OK, 2 rows affected (0.03 sec)
    
    Rows matched: 2 Changed: 0 Warnings: 0

    Depending on how many rows the query will check, this may take some time. Updating the “meta_value” on one of my sites with almost 19,000 posts returned this console output:

    sitedb_wp> UPDATE wp_postmeta SET meta_value = replace(meta_value, 'https://www.my-old-url.com', 'https://www.my-new-url.com')
    [2023-10-02 10:23:42] 231,918 rows affected in 1 s 27 ms

    And likewise, updating the “post_content” column returned this console output:

    sitedb_wp> UPDATE wp_posts SET post_content = replace(post_content, 'https://www.my-old-url.com', 'https://www.my-new-url.com')
    [2023-10-02 10:26:03] 86,156 rows affected in 38 s 573 ms

    Keep in mind that I’m executing these queries on an AWS RDS instance that is size db.t3.medium so take your particular database infrastructure into account when running these commands. I can personally confirm that these queries work on WordPress versions 4.8.x up to 6.3.x. I don’t see this changing in future WordPress versions but who knows. Also, these queries do not take into account any third-party plugins or data that said plugins may be storing in your site’s database.