WordPress API: ‘slug already exists’ on publish — the honest fix

Introduction

Understanding the slug conflict scenario

This error usually isn’t a real duplicate; it’s a race between autosave, REST create, and WordPress’s slug sanitiser that leaves a stale post_name behind. The reliable fix is to resolve the collision server-side: normalise the desired slug, call wp_unique_post_slug for the post_type and status, and hard-fail or clear conflicts when a trashed or draft twin exists instead of silently incrementing.

Impact on publishing workflow and SEO

Slug conflicts slow workflows, risk duplicate content, and can hurt SEO. A clean, validated slug streamlines publishing and keeps URLs stable for users and search engines.

Strategies to Ensure Unique Slugs via the WordPress API

Using wp_unique_post_slug for slug validation

WordPress offers a function to validate slugs by checking existing posts for the same slug. Using wp_unique_post_slug helps prevent duplicates before publishing or updating, keeping URLs stable across posts and custom post types.

• Pass the proposed slug, post_ID, and post type to wp_unique_post_slug to obtain a unique variant.
• If the slug exists, WordPress often appends a numeric suffix, which can preserve readability.
• Use the returned value as the canonical slug before insertion or update.

Automatically generating and validating slugs on publish

Automate slug generation at publish time to align with the post title and content, reducing manual edits and title-change conflicts.

• Intercept publish actions with wp_insert_post or REST API hooks to derive the slug from post_title or other fields.
• Validate the slug against existing posts, pages, and custom post types to ensure uniqueness.
• Store the final slug in the post data and proceed with publish or update.

Practical Implementation Tips

Server-side checks before post creation

Rely on server side validation to catch slug conflicts before a post is saved. This reduces round trips and ensures consistency across post types, including custom post types and events. Use core functions to verify uniqueness and to derive a clean slug from the title when needed.

• If the slug changes during validation, apply the final slug to the post data before insertion or update.
• Store the slug in the post data as the canonical identifier to prevent future conflicts.

Handling concurrency and race conditions

When multiple requests publish the same slug, race conditions can occur. Implement locking and atomic operations to maintain integrity, and consider database level safeguards if your hosting supports them. Track the slug lock during the publish flow to avoid duplicate inserts.

• Use wp_insert_post or wp_update_post within a single transactional context if the environment supports it.
• Leverage wp_ajax checks for asynchronous slug validation to provide instant feedback without duplicating posts.
• Log conflicts and provide a fallback path, such as suggesting a slightly altered slug while preserving the original title.

FAQ

What causes the slug already exists error when publishing

Slug conflicts occur when another post, page, or custom post type uses the same slug derived from the title or a manual slug entry. Concurrency and race conditions can also trigger duplicates if checks happen after insertion attempts.

How to prevent duplicate slugs

• Validate the slug on the server side before insert or update
• Use wp_unique_post_slug to obtain a unique variant if needed
• Consider implementing an ajax slug check during editing to give immediate feedback

What should I do if a duplicate slug already exists

• Let WordPress auto append a numeric suffix or manually adjust to a unique slug
• Ensure the final slug is stored consistently in the post data

Conclusion

Slug conflicts can disrupt the publish flow. Validate and generate unique slugs at edit or publish time using core functions and AJAX checks to prevent duplicate titles from becoming duplicate slugs.