A prospective WordPress site can contain every expected Page and Blog Post while its resource archives, member access, or dynamically rendered content no longer work. Prevention depends on preserving the content model and the components that consume it, alongside the visible records.
A page-only inventory can miss the definitions, relationships and operating boundaries that make WordPress content useful. Record counts cannot establish that the target can edit, render, authorize or route the agreed content.
Start with the actual Source records and the intended WordPress result. A WordPress Source needs its installed definitions and storage owners; another Source needs its own structures qualified before mapping.
Assign Target responsibilities and prove representative relationships. Native WordPress or plugin capability does not establish migration coverage, and copying every database value does not establish usable content.
Pitfall 1: Planning Only Pages and Posts
What goes wrong
A Page/Post-only scope can leave other dependencies unplanned:
- Content and presentation: menus, media, templates, widgets, blocks and shortcodes.
- Relationships and authority: comments, authors, users and roles.
- Structure and continuity: custom types, taxonomies, plugin records, SEO fields and redirects.
Content totals can look complete while the site remains unusable:
- Editors cannot update Pages properly.
- Visitors encounter broken links.
- Library media is absent from Pages.
- Custom content loses structure.
- Account-based access stops 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 operating role before migration:
- Brochure site, blog, resource library or documentation center.
- Membership, event or directory application.
- Content connected to commerce.
Each needs its own combination of content types, permissions, templates, URLs and plugin relationships.
Map core and structured content, media, menus, users, permissions and plugin dependencies alongside URLs, redirects, SEO fields and Target configuration.
Use WordPress preparation to assemble actual evidence. Sample ordinary Pages and complex records; the available migration path and separate implementation determine what can be tested.
Recommendation example
Illustrative resource-library sample:
- Homepage, parent/child Pages and a Blog Post.
- Downloadable resource, taxonomy archive and media-heavy Page.
- Contributor user and redirect-sensitive URL.
Review the relationships among them, not only isolated records.
Pass condition
The agreed publishing, navigation, media, permission and content-structure outcomes are demonstrated.
Mapping correction, Target configuration, custom implementation, manual reconstruction, approved exclusion or an accepted limitation can resolve a finding. A proposed treatment or assigned owner alone does not Pass a required outcome.
Pitfall 2: Flattening Structured Content
What goes wrong
Unapproved conversion of custom types or taxonomies into ordinary Pages can preserve text while losing meaning:
- Events lose dates and venues.
- Directories lose listing fields.
- Staff profiles lose department groupings.
- Resources lose filters.
- Archives return the wrong result.
An approved redesign is judged by its agreed use; unintended flattening is the pitfall.
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
For each custom type or taxonomy, define:
- Target record type, fields and taxonomy relationships.
- Required archives, URL patterns, templates and filters.
- Representative records that demonstrate the agreed content model.
Public exposure is required only where intended.
Use compatible supported mapping where it handles the actual values and relationships. Custom tables, serialized structures or plugin labels do not automatically require tailored handling; qualify the extraction, interpretation and consumer first.
Where the supported path is insufficient, agree separate implementation, redesign or exclusion. Copied records do not register their type or taxonomy. Confirm the Target component supplying required editor, permission, archive and rendering behavior.
API exposure is separate. Absence from an ordinary response does not prove a stored custom type is unused.
Recommendation example
Illustrative directory sample:
- Listings, listing categories and location taxonomies.
- Contact fields, map data and featured images.
- Related users and archive Pages.
Prove the intended listing behavior, not just its title.
Pass condition
Required type and taxonomy meaning, relationships, archives, URLs, editing and public or restricted use meet the agreed model. An approved conversion can Pass when its intended outcome is demonstrated.
Pitfall 3: Moving Metadata Without Its Meaning
What goes wrong
Metadata can mix useful meaning with technical residue:
- Display values, SEO/schema fields and access rules.
- Event dates, membership states and builder settings.
- Integration IDs, cache fragments and obsolete plugin residue.
Copying all fields can add clutter while missing the values the site needs.
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 before transfer:
- Display, relationship and SEO fields.
- Access, user and integration fields.
- Plugin settings, cache values and deliberate exclusions.
Use the metadata and extension model to identify literal values, references and consumers. Test required editing, display, filtering, permissions and integration behavior.
Use supported field mapping for compatible values. Qualify serialized logic, plugin relationships, custom tables and external dependencies against actual handling and the intended consumer; agree separate interpretation, Target implementation or exclusion where needed.
Recommendation example
Illustrative property listing: check price, address, availability, property type, agent, map coordinates, gallery and contact details in the intended template.
Existing field keys alone do not demonstrate that result.
Pass condition
Required display, search, filtering, access, integration, SEO and workflow metadata is usable through its intended consumer. Editing is required where agreed; protected or system-managed values need their intended access behavior, not universal administrator editability.
Pitfall 4: Expecting Automatic Layout Reconstruction
What goes wrong
Layout can depend on blocks, builders, shortcodes, widgets, reusable sections, theme options, template parts or custom blocks.
Text can survive while these outputs fail:
- Visual structure and template behavior.
- Forms, sliders, galleries and calls to action.
- Embeds and reusable layouts.
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. |
| Identical visual output is expected without agreed reconstruction work. | 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
Assign each Page an agreed presentation treatment:
- Preserve required layout behavior.
- Retain reusable content only.
- Rebuild manually.
- Implement a builder-specific structure separately.
Separate record transfer from reconstruction responsibilities.
Sample high-value Page types and inspect both editing and visitor output. Classify differences as content correction, Target theme work, manual reconstruction, custom implementation or accepted limitation.
Saved markup and dynamic rendering are different evidence. A dynamic block may need continuing code and current data; any saved fallback can be less capable. Review intended behavior rather than accepting preserved text or a placeholder.
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 demonstrate usable agreed layout behavior or the completed required reconstruction, redesign or implementation. An approved exclusion can meet scope; a rebuild plan alone does not Pass an unproven launch requirement.
Pitfall 5: Losing Media References
What goes wrong
A populated media library can coexist with:
- Broken images, missing featured images or galleries.
- Missing downloads, empty sliders or failed embeds.
- Unintended links to a retiring Source origin.
Media is a reference layer, not only a file count. Agreed external assets need their own continuing owner.
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 rely on the old domain without an agreed continuity plan. | Launch can create broken assets and SEO issues. |
Prevention
Review media through its uses:
- Inline and featured images, galleries and downloads.
- Captions, alt text, metadata and embeds.
- Builder media modules and custom-type templates.
Prove references resolve to the agreed assets.
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 uses the correct images, featured images, galleries, embeds, downloads, captions and references. It has no unintended dependency on a retiring Source site; deliberately retained remote assets have confirmed continuity.
Pitfall 6: Losing User and Access Meaning
What goes wrong
A username can serve different purposes:
- Author, editor or subscriber.
- Member, student, instructor, donor, agent or vendor.
- Forum user, community member or plugin-defined account.
Roles and capabilities can govern private content, downloads, publishing, courses, memberships, directories or submissions. Core identity alone does not establish those uses.
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 roles, account types, capabilities, access rules, authorship and plugin-owned user metadata. Test users from each material group against intended Target permissions, including a task that must be denied.
Password continuity depends on the exact supported Source-to-Target path. Confirm reset, activation or first-login handling where continuity is unavailable.
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
Illustrative account sample, where relevant:
- Administrator, editor, author and subscriber.
- Member, student, instructor, vendor, donor and customer-like user.
Check administration access, restricted content, authorship, profile fields and the relevant plugin 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: Reducing SEO to Slugs and Titles
What goes wrong
SEO continuity spans connected controls:
- Routes: slugs, permalinks, redirects, canonicals, taxonomy archives and internal links.
- Search presentation: titles, descriptions, schema fields, alt text and plugin metadata.
- Discovery rules: robots settings and sitemap behavior.
Preserved body content does not establish those outcomes.
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
Build the URL and redirect plan before cutover. Sample high-traffic Pages, Blog Posts, taxonomy/custom-type archives, media URLs and downloads.
Include internal links inside content and builder modules; they can retain old destinations even when the visible Page works.
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 and their approved redirects resolve to relevant destinations. Internal links work, search metadata is preserved or intentionally revised, and required SEO archives remain discoverable. Approval on paper alone is not redirect evidence.
Pitfall 8: Mixing CMS and Commerce Scope
What goes wrong
A generic CMS scope can overlook required commerce meaning:
- Products, Orders, Customer accounts and checkout fields.
- Coupons, subscriptions and commerce extensions.
- Tax/shipping settings and payment context.
Qualify these through the actual commerce layer, not WordPress core.
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
Keep two owners distinct:
- CMS: content, users, roles, media, menus, URLs and structured content, with named plugins for their functions.
- Commerce: Products, Orders, Customers, coupons, checkout, tax/shipping, payments, subscriptions and extensions where required.
The WooCommerce overview explains that additional model. Its native capabilities do not establish coverage for a particular migration path.
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: Losing Multisite Boundaries
What goes wrong
Treating Multisite as one ordinary site can lose the context around content, media, menus, domains, options, roles and plugins.
- Content can appear under the wrong domain.
- Users can receive incorrect permissions.
- A site can lose the settings or components interpreting its records.
Shared administration or identity does not merge those ownership boundaries.
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 are enabled for network/site availability, and plugins can be network- or site-activated. | 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
Prepare a site-by-site map:
- Domain/path and intended Target destination.
- Content types, taxonomies, media, menus, URLs and redirects.
- Site roles, theme dependencies and plugins.
Separate shared identity from site capabilities, and network settings from ordinary content. Resolve objects with their site identity rather than a numeric content ID alone.
| 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
Illustrative university network: map admissions, research and departmental sites before deciding whether they remain separate or consolidate intentionally.
Keep each domain, editor group, custom type, media set and navigation visible in that decision. Do not flatten them into one Page collection by accident.
Pass condition
Each site’s agreed owner, domain/path, content boundary, permissions and dependencies are demonstrated in the Target arrangement. Shared users retain intended site access, and content/media follow the approved separate or consolidated model. A declared dependency plan alone is not proof.
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 demonstrate their agreed structure and required archive or restricted-use behavior. |
| Metadata | Classify fields by purpose and target consumer. | Important values are usable through the intended template or integration, with editing and access required by the agreed field meaning. |
| Presentation | Separate transferable content from builder, theme, and layout reconstruction. | Priority Pages demonstrate the agreed usable presentation; required rebuilds are complete or explicitly excluded by agreement. |
| Media | Preserve attachment and embedded-asset relationships, not only files. | Priority content uses correct images, galleries and downloads without unintended Source reliance; agreed remote assets have confirmed continuity. |
| 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
Prevent WordPress migration failures by retaining agreed relationships and their consumers. Content types, metadata, presentation, media, access, routes, commerce and site boundaries need different evidence; Page and Post totals cannot substitute for it.
Use representative examples and explicit responsibilities, then apply WordPress validation to the agreed result.
Unsupported or obsolete structures can be redesigned, archived or excluded deliberately. A proven agreed outcome can Pass; remaining nonblocking work is distinct from a required missing result. Ownership or a proposed fix does not replace evidence.
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?
Unintended flattening can preserve text while losing required fields, taxonomies, archives, filters, templates and URLs. Judge any deliberate conversion by its agreed target use; not every custom type must remain identical or expose a public archive.
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.
Does copying custom post type records recreate their WordPress definition?
No. The target must supply the registered content type, connected taxonomies, and intended archive, editor, and permission behavior through its own implementation.
If extraction uses an API, confirm the configured exposure of those types separately. Existing records and an absent API response are different evidence; neither establishes that the target content model is complete.
Does saved block content prove that a WordPress page will remain functional?
No. Static blocks can retain saved markup, while dynamic blocks depend on rendering code and the data it uses. Some dynamic blocks also save fallback HTML, but that fallback may not preserve the intended interaction or current result.
Review editing and visitor behavior with the continuing target components, especially where a block drives listings, forms, or restricted content.