How to migrate ACF fields between WordPress sites without breaking ID references
Push a post with Advanced Custom Fields to another site, and most of what you see looks fine — the text fields, the WYSIWYG content, the straightforward stuff. Then you open a Relationship field and it's pointing at some unrelated post. A Gallery field shows broken images. A Post Object field that should link to "our pricing page" links to whatever post happened to land on ID 482 on the new site. Nothing errored. The push "succeeded." It just quietly moved the wrong thing.
Why copying the value isn't enough
Most of what a plain export/import does with post meta is copy the raw value across unchanged — which is exactly right for a text field, and exactly wrong for a Relationship, Post Object, Image, File, Gallery, Taxonomy, or User field. Those field types don't store a photo or a post; they store a reference to one — a database ID, or in the case of a term or user field, an identity that was only ever meaningful on the site that created it. Copy the ID and you've copied a pointer into an address space that doesn't exist where it's landing. The same identifier problem shows up anywhere two WordPress databases meet, which the first post on this blog covers in general — ACF fields are just one of the more common places it bites.
How ACF actually stores a field, and why that matters here
Every ACF field value sits in ordinary post meta under its own key, with a quiet companion entry — the same key prefixed with an underscore — holding the field's definition key (field_...). That companion is how ACF's own get_field_object() turns a bare meta key back into a real field type at read time, and it's also how a migration tool can tell a Relationship field apart from a plain text field without guessing from the key's name.
It's also why Repeater, Flexible Content, and Group fields don't need any special-case handling at all. ACF doesn't store a repeater as one nested blob — it flattens every row and sub-field into its own ordinary meta key (an Image field buried three rows into a repeater ends up as something like gallery_items_2_image, with its own _ companion pointing straight at the Image field's definition). Scan every meta key on a post, not just the top-level ones, and a sub-field three levels deep gets classified exactly the same way a top-level field would. Only the repeater's own row-count marker needs no handling — it's a plain integer with no reference of its own.
Three different kinds of reference, three different fixes
Not every ACF field that stores an ID needs the same resolution:
- Image, File, Gallery, Relationship, Post Object — these store an attachment or post ID, and attachments and posts both live in the same ID space. A migrated attachment or post gets a new ID on the destination the moment it's imported, so the field has to be rewritten to whatever that new ID turns out to be.
- Taxonomy — a term ID isn't portable either, but a term also isn't the same kind of object as a post, so it resolves differently: by taxonomy and slug, looking up (or creating) the matching term on the destination rather than trying to reuse the source's numeric ID.
- User — same story, resolved by email or login instead of a raw user ID, since the two sites' user tables were never the same table to begin with.
The part that's easy to get wrong
The tempting shortcut is: if a reference can't be resolved on the destination, just leave the old value in place. That's actually the worse outcome. An unresolved source-site ID doesn't become "empty" on the destination — it becomes whatever post, attachment, or user happens to occupy that same ID number over there, which is pure coincidence and usually unrelated content. A Relationship field that can't find its real match should end up empty, not pointed at a stranger. The same applies mid-migration: pushing a page whose Relationship field points at a post you haven't migrated yet should drop that reference rather than leave a dangling ID that resolves to nothing — or worse, to something else entirely once post IDs start overlapping between sites.
What PostDeploy does about all of this
Pushing a post scans every meta key for ACF's field-definition companion, classifies each one by its real field type, and handles the three cases above on the receiving end — after the destination post and any migrated attachments already exist, so there's something real to resolve against. Image, File, and Gallery fields reuse the same media import path featured images and content images already go through, rather than a separate ACF-only pipeline. Relationship and Post Object fields resolve through the same source-to-destination object mapping every other cross-site reference in PostDeploy uses. Taxonomy fields resolve (or create) the matching term by slug; User fields resolve by a remembered mapping first, then by email or login. Anything that genuinely can't be resolved is removed from the field rather than left pointing at whatever unrelated content happens to share that old ID on the new site.
Try it
PostDeploy Free moves Posts, Pages, and custom post types as plain content. PostDeploy Pro adds the ACF field resolution described here — see the ACF integration page for the full field-type list — along with Elementor and WPML reference resolution.