WordPress migrations fail most often when the site is treated as a collection of Pages and Blog Posts instead of a configurable publishing environment. Custom post types, taxonomies, metadata, plugins, themes, media relationships, user capabilities, permalink rules, and network boundaries can all carry business meaning that ordinary content counts do not reveal.
Prevention starts by identifying what makes the source site behave as it does, assigning each dependency a target owner, and proving representative relationships rather than copying every database value indiscriminately. The following pitfalls focus on recurring WordPress-specific failure patterns and the controls that keep the target site usable for editors, visitors, and connected systems.
Pitfall 1: Treating WordPress as Only Pages and Posts
What goes wrong
The migration scope focuses on ordinary CMS Pages and Blog Posts while ignoring the broader WordPress site model. Menus, media relationships, comments, authors, templates, widgets, blocks, shortcodes, SEO fields, redirects, users, roles, custom post types, custom taxonomies, and plugin-owned records may be left unplanned.
The result can look complete in content counts while the target site still fails as a real publishing environment. Editors may find pages difficult to update. Visitors may hit broken links. Media may appear in the library but not on pages. Custom content may lose structure. Account-based access may stop working.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| The scope only lists CMS Pages and Blog Posts. | Important WordPress relationships may be missing. |
| Menus, media, comments, users, roles, and redirects are not sampled. | Site usability may fail even when content exists. |
| Custom post types are described as pages. | Structured content may be flattened. |
| Plugin data is assumed to be part of normal content migration. | Unsupported records may be discovered too late. |
Prevention
Define the target WordPress operating role before migration. A brochure site, blog, resource library, membership site, event site, directory, documentation center, or content-commerce site each depends on a different combination of content types, permissions, templates, URLs, and plugin relationships.
Map core content, structured content, media, menus, users, permissions, plugin dependencies, URLs, redirects, SEO fields, and target-side configuration tasks. Representative samples should include ordinary Pages and complex records rather than only clean Blog Posts.
Recommendation example
For a resource-library site, sample the homepage, a parent page, a child page, a Blog Post, a downloadable-resource record, a taxonomy archive, a media-heavy page, a contributor user, and a redirect-sensitive URL.
Pass condition
The target WordPress site supports the intended publishing, navigation, media, permission, and content-structure workflows. Every missing element has an explicit owner and a controlled outcome: mapping correction, target configuration, custom implementation, manual reconstruction, deliberate exclusion, or accepted limitation.
Pitfall 2: Flattening Custom Post Types and Taxonomies
What goes wrong
Custom post types and custom taxonomies are migrated as ordinary pages or Blog Posts. Record titles and body content may survive, but structured meaning is lost. Events lose dates and venues, directories lose listing fields, staff profiles lose department groupings, resources lose filters, and archive pages stop behaving as expected.
This pitfall is especially damaging when custom post types drive navigation, search, filtering, landing pages, directories, maps, documentation, course libraries, or structured content strategy.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| The source site has Events, Courses, Listings, Staff, Resources, Locations, Portfolio, Jobs, or Documentation records. | Important content may not be ordinary pages. |
| Custom taxonomies control browsing or filters. | Category-like relationships may require special mapping. |
| Archive pages, listing grids, or filter views are business-critical. | Target behavior depends on more than record transfer. |
| The target implementation uses a different plugin, theme, or content model. | Same labels may not mean same structure. |
Prevention
Inventory every custom post type and custom taxonomy. For each structure, identify the target record type, fields, taxonomy relationships, archive expectations, URL pattern, display templates, and filter behavior. Use representative records to confirm that the target preserves the content model rather than flattening it.
Use supported field mapping where the relationship is explicit. Records that depend on custom tables, serialized structures, plugin-defined relationships, or target-specific rendering need a separate custom implementation or deliberate redesign decision.
Recommendation example
For a directory site, test business listings, listing categories, location taxonomies, contact fields, map data, featured images, related users, and archive pages. The test should prove that a listing behaves as a listing, not only that its title migrated.
Pass condition
Important custom post types and taxonomies keep their intended record type, relationships, archive behavior, URL structure, editability, and front-end usability.
Pitfall 3: Migrating Metadata Without Understanding Its Purpose
What goes wrong
WordPress metadata is moved without deciding which fields are meaningful. Custom fields can store display values, SEO fields, schema data, access rules, event dates, membership states, page-builder settings, integration IDs, cache fragments, or obsolete plugin residue. Moving all fields can create clutter while still failing to preserve the fields that matter.
The risk increases when the target site changes theme, builder, plugin stack, or content model. A field may exist in the database but remain invisible because the target template or plugin does not read it.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| The source uses custom fields, ACF-style field groups, theme meta boxes, or custom-coded metadata. | Business meaning may live outside visible content. |
| Field inventory is large but ownership is unclear. | The migration may carry noise and miss key meaning. |
| Target theme or plugin stack differs from the source. | Field values may not display or function. |
| Integration IDs or access fields are mixed with display fields. | Operational records may need custom interpretation. |
Prevention
Classify metadata by purpose: display fields, relationship fields, SEO fields, access fields, integration IDs, user fields, plugin settings, cache values, and fields to exclude. Validate high-value fields by admin editability, front-end display, filtering behavior, permissions, and integration continuity.
Use supported field mapping for clear field-to-field relationships. Serialized logic, plugin-specific relationships, custom tables, and external-system dependencies need custom interpretation, target-side implementation, or deliberate exclusion.
Recommendation example
For a real estate site, validate listing price, address, availability, property type, agent assignment, map coordinates, gallery, and contact details in the target listing template. Do not accept the result only because field keys exist.
Pass condition
Metadata needed for display, search, filtering, access, integrations, SEO, or business workflows is readable, editable, and used by the target WordPress environment as intended.
Pitfall 4: Assuming Page Builders and Themes Reconstruct Automatically
What goes wrong
Blocks, page builders, shortcodes, widgets, reusable sections, theme options, template parts, and custom blocks can store layout outside plain content. A migration can preserve page text while losing visual structure, forms, sliders, galleries, call-to-action areas, embeds, reusable layouts, or template behavior.
This issue becomes more serious when the target site changes theme, builder, block library, or design system. Data migration may not recreate design reconstruction.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| Pages use Elementor, Divi, WPBakery, Beaver Builder, Gutenberg blocks, custom blocks, or theme modules. | Layout may depend on builder-specific data. |
| Target uses a different builder or theme. | Source layout data may not render. |
| The merchant expects identical visual output. | Migration and redesign work are being confused. |
| Important pages include forms, sliders, galleries, reusable widgets, or embedded scripts. | Functional layout elements may need separate handling. |
Prevention
Separate content transfer from visual reconstruction. Identify pages that must preserve layout, pages that only need reusable content, pages that require manual rebuilding, and builder structures that need custom implementation.
Representative samples should include high-value Page types, not only simple posts. Review both admin content and front-end output. Presentation differences should be assigned to content correction, target-side theme work, manual reconstruction, custom implementation, or accepted limitation.
Recommendation example
Sample the homepage, a service landing page, a media-heavy CMS Page, a form page, a Blog Post with blocks, and a custom post type record. Compare the target front end against the intended launch result and decide what belongs to migration versus redesign.
Pass condition
Priority pages either retain usable layout behavior or have an agreed reconstruction, redesign, exclusion, or custom implementation path.
Pitfall 5: Losing Media Relationships and Embedded Asset Context
What goes wrong
Media files may exist in the target library while pages still show broken images, missing featured images, old-domain URLs, broken galleries, missing downloads, empty sliders, or embedded assets that point to the source site. WordPress media is a relationship layer, not only a file count.
Media affects content display, featured images, SEO metadata, alt text, captions, downloadable resources, builder modules, galleries, and custom post type templates. If these relationships are not validated, the library can look complete while the site remains visually broken.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| Media count looks correct but images do not display on priority pages. | File movement and content relationships are not the same. |
| Featured images are missing from archives or custom post types. | Theme and listing layouts may break. |
| Galleries, sliders, PDFs, downloads, or embedded files fail. | Business-critical assets may be disconnected. |
| Image URLs still point to the old domain. | Launch can create broken assets and SEO issues. |
Prevention
Validate media by relationship. Review inline images, featured images, galleries, downloads, captions, alt text, media metadata, embedded content, page-builder media modules, and files used by custom post types.
If asset references require path rewriting, relationship mapping, or builder-specific handling, assign them to content correction, target configuration, or custom implementation.
Recommendation example
Review a long-form Blog Post, a media-heavy CMS Page, a custom post type record with a gallery, a downloadable-resource page, and a landing page with builder-controlled images.
Pass condition
Priority content displays correct images, featured images, galleries, embedded assets, downloadable files, captions, and media references without relying on the source site.
Pitfall 6: Underestimating Users, Roles, Permissions, and Account Meaning
What goes wrong
WordPress users are migrated as simple account records. Their actual meaning may be author, editor, subscriber, member, student, instructor, donor, agent, vendor, forum user, community member, or plugin-defined account type. Roles and capabilities may control private content, downloads, publishing workflows, course access, membership status, directories, or submissions.
If users are migrated without role and permission context, records may exist but fail to provide usable access.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| The source has membership, LMS, forum, vendor, directory, booking, donation, or community behavior. | User meaning may be plugin-defined. |
| Roles go beyond default WordPress roles. | Capabilities may need target review. |
| Private content or downloads depend on access rules. | Simple user migration may not preserve authorization. |
| Password continuity or login behavior is assumed. | Authentication may require separate planning. |
Prevention
Inventory user roles, account types, capabilities, access rules, authored-content relationships, and plugin-owned user metadata. Review representative users from each important account type against the intended target permissions.
When user meaning is tied to memberships, learning progress, donations, vendor records, forum reputation, or custom tables, define whether that meaning will be preserved through target configuration, custom implementation, manual reconstruction, or deliberate exclusion.
Recommendation example
Test administrator, editor, author, subscriber, member, student, instructor, vendor, donor, and customer-like accounts where relevant. Confirm dashboard access, restricted content, authored content, profile fields, and plugin-specific account behavior.
Pass condition
Important users retain the correct role meaning, access behavior, authored content relationships, and account usability expected in the target WordPress site.
Pitfall 7: Treating SEO as Only Slugs and Titles
What goes wrong
WordPress SEO continuity depends on slugs, permalink structure, redirects, canonical URLs, SEO titles, meta descriptions, schema fields, taxonomy archives, robots settings, image alt text, sitemap behavior, internal links, and SEO plugin metadata. A migration can preserve content while damaging traffic if routing and metadata are not planned.
The risk increases when the target site changes permalink structure, theme, SEO plugin, taxonomy structure, language setup, or page-builder output.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| Target permalink structure is not confirmed. | Existing URLs may break. |
| Source and target SEO plugins differ. | Metadata may not map directly. |
| Taxonomy archives or custom post type archives drive traffic. | Archive URLs may need separate validation. |
| Internal links still point to the old domain or old paths. | Visitors and crawlers may hit broken paths. |
Prevention
Create a priority URL and SEO sample set before cutover. Include high-traffic pages, Blog Posts, taxonomy archives, custom post type archives, media URLs, downloadable files, and internal links inside content or builder modules.
Validate redirects, SEO metadata, canonical values, internal links, index settings, schema fields where relevant, and sitemap behavior. If SEO plugin metadata cannot be translated directly, define field mapping, target-side configuration, manual reconstruction, or deliberate exclusion before cutover.
Recommendation example
For a content-heavy site, validate the homepage, top organic landing pages, top Blog Posts, important category/tag archives, custom post type archives, high-value media downloads, and legacy URLs with redirect plans.
Pass condition
Priority URLs resolve correctly, redirects are approved, internal links are updated, search-sensitive metadata is preserved or intentionally revised, and SEO-critical archives remain discoverable.
Pitfall 8: Confusing WordPress Scope With Commerce Scope
What goes wrong
A site that contains WooCommerce or other commerce-like plugin behavior is treated as a generic WordPress migration. CMS content may migrate well, but product records, orders, customer accounts, checkout fields, coupons, subscriptions, tax/shipping settings, payment context, and commerce extensions may require separate commerce-specific planning.
The opposite mistake can also happen: the project becomes commerce-focused and ignores WordPress pages, Blog Posts, media, menus, custom post types, SEO, and user-role context.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| Products, orders, customers, subscriptions, or checkout records are mentioned inside a WordPress scope without separate commerce review. | Commerce records may need different validation and handling-path decisions. |
| CMS Pages and Blog Posts are treated as secondary because commerce data is larger. | Content and SEO continuity can be underplanned. |
| User accounts include both editorial and customer meanings. | Generic user migration may blur account purpose. |
| Plugins create both content and commerce records. | CMS and commerce ownership may be unclear. |
Prevention
Separate CMS-site ownership from commerce ownership before mapping records. WordPress should own site content, users, roles, media, menus, URLs, plugins, and structured content. WooCommerce or another commerce layer should own products, orders, customers, coupons, checkout, tax/shipping, payment context, subscriptions, and commerce extensions where relevant.
Use shared samples only where the relationship matters, such as customer-like users, product landing pages, media assets, SEO paths, or commerce-connected content.
Recommendation example
For a WordPress site with a store, validate a CMS Page, Blog Post, custom post type record, product page, customer account, order record, media-heavy landing page, top organic URL, and plugin-owned checkout field as separate but connected samples.
Pass condition
CMS and commerce expectations are separated, shared dependencies are documented, and each record type is reviewed through the correct WordPress or commerce-specific ownership model.
Pitfall 9: Ignoring Multisite Network Boundaries and Site Ownership
What goes wrong
A WordPress Multisite network is treated as one ordinary site. Content, media, menus, domains, site options, user roles, and plugin behavior may belong to different sites even when the network shares administration or user records. Combining those boundaries can place content under the wrong domain, grant the wrong permissions, or detach a site from the settings and plugins that make it usable.
The same mistake can occur when a source installation is not formally Multisite but still hosts several business units, languages, brands, or microsites through custom routing and shared tables.
Early warning signs
| Warning sign | Why it matters |
|---|---|
| The source has a network dashboard, multiple site URLs, or site-specific administrators. | The project may contain several ownership boundaries rather than one content pool. |
| Users have different roles on different sites. | A single global role mapping can overgrant or remove access. |
| Themes or plugins are activated at network level and site level. | The same content type may behave differently by site. |
| Media, menus, domains, or options differ between sites. | Combining records can break routing and editorial ownership. |
Prevention
Create a site-by-site ownership map before mapping records. For every site, record its domain or path, active content types, taxonomies, media, menus, user roles, theme dependencies, plugins, redirects, and target destination. Shared users should be separated from site-specific capabilities, and network-level settings should be distinguished from ordinary content.
| Network layer | Required decision |
|---|---|
| Site identity | Preserve as a separate site, consolidate intentionally, or retire. |
| Users and roles | Preserve shared identity while mapping site-specific capabilities. |
| Content and media | Keep each record attached to the correct site and URL context. |
| Plugins and settings | Rebuild only the behavior needed by the target site arrangement. |
Recommendation example
For a university network, do not merge the admissions site, research site, and departmental sites into one Page collection. Map each site’s domain, editors, custom post types, media, and navigation separately, then decide which sites remain independent and which content is intentionally consolidated.
Pass condition
Every source site has a declared target owner, domain or path, content boundary, permission model, and dependency plan. Shared users remain usable without losing site-specific roles, and no content or media is attached to the wrong site context.
Cross-Pitfall Prevention Priorities
| Control area | Prevention priority | Evidence of control |
|---|---|---|
| Content model | Distinguish Pages, Blog Posts, custom post types, taxonomies, and plugin-owned records. | Representative records retain their intended structure and archive behavior. |
| Metadata | Classify fields by purpose and target consumer. | Important values are readable, editable, and used by the intended template or integration. |
| Presentation | Separate transferable content from builder, theme, and layout reconstruction. | Priority pages have a usable target presentation or a controlled rebuild plan. |
| Media | Preserve attachment and embedded-asset relationships, not only files. | Priority content displays the correct images, galleries, and downloads without source dependencies. |
| Identity | Map users, roles, capabilities, and access rules by business function. | Representative accounts have the intended permissions and authored-content relationships. |
| Routing | Treat permalinks, archives, redirects, and internal links as one route system. | Priority paths resolve to relevant destinations and archive structures remain discoverable. |
| Site boundaries | Separate WordPress CMS ownership, commerce ownership, and Multisite ownership. | Each record belongs to the correct site, plugin, and operational owner. |
Conclusion
WordPress migration pitfalls are preventable when the project preserves the relationships that make the site function: custom content types, taxonomies, metadata consumers, builder dependencies, media references, user capabilities, permalink structures, commerce boundaries, and site ownership. Copying Pages and Blog Posts without those relationships produces a technically populated but operationally weak site.
The strongest result comes from representative examples, explicit ownership decisions, and pass conditions tied to real editorial and visitor behavior. Unsupported or obsolete structures should be redesigned or excluded deliberately rather than carried forward without a target consumer.
Common Questions
Why can a WordPress migration look complete while the site still fails?
Record counts can be correct while menus, media relationships, custom content, plugin-owned fields, permissions, archives, or redirects remain disconnected. WordPress usability depends on those relationships, not only on Page and Blog Post totals.
What is the biggest risk with custom post types?
The biggest risk is flattening a structured record into an ordinary Page or Blog Post. The title and body may survive while fields, taxonomies, archives, filters, templates, and URLs lose their original purpose.
Should page-builder layouts be expected to transfer automatically?
No. Builder layouts, theme modules, shortcodes, widgets, and reusable sections often depend on plugin- or theme-specific structures. Preserve reusable content where possible, then assign layout reconstruction to the target implementation.
How should WordPress metadata be handled?
Classify metadata by purpose and target consumer. Preserve values used for display, search, access, SEO, or integrations; restructure fields when the target model differs; and exclude cache fragments or obsolete plugin residue.
Why are users and roles more complex than account records?
A user may be an author, editor, member, student, donor, vendor, or network administrator. The migration must preserve the relevant capabilities, content ownership, and access relationships rather than only a username and email address.
What changes when the source uses WordPress Multisite?
Each site can have its own domain or path, content, media, menus, roles, themes, plugins, and settings. The target plan must preserve or intentionally consolidate those boundaries instead of treating the network as one undifferentiated site.