Advanced Custom Fields is easy to start and expensive to change. That is not a criticism of ACF. It is what happens when a schema tool stores values under field names, then lets you rename those names in the admin as if the database will follow.
It does not follow.
On an ACF Pro site with real content, dragging a field into another group, renaming a field, or wrapping loose fields into a group is a schema edit. The posts, terms, users and options pages that already hold values keep the old meta keys. Templates keep calling the old names. Editors open a page and see empty fields next to content that is still in the database, just no longer attached to the field they are looking at.
This is the ACF trap: the interface looks like a layout tool. The storage is a migration problem.
What actually happens when you move a field
ACF stores field definitions in field groups. Those definitions describe a name, a type, a parent, and a location. Content is stored separately, usually as post meta, term meta, user meta, or options.
The connection between the two is the field name. Change the name, or move the field so the key path changes, and you have two artefacts that no longer agree:
- The field group now describes a field that has never been saved.
- The old meta keys still exist, often in the thousands, with no UI pointing at them.
Repeaters, flexible content and group fields make this worse. Nested rows encode parent keys into the meta structure. Moving a sub-field is not a single rename. It is a tree rewrite. Miss a branch and you orphan a slice of every row.
Local JSON, if you use it, records the new schema. Production content still has the old keys. The next deploy looks clean in git and empty in the editor.
Why this shows up late
The trap is quiet on a new build. You can reshuffle fields while the site is still in development and nobody has typed into them. Agencies do this constantly. The damage starts after launch, when:
- A client wants the hero CTA on a different field group.
- A developer wraps three related fields into a group for sanity.
- A rename is required because two groups used
cta_text. - A page template is split and the fields need to live on a new post type.
Those are ordinary requests. They are also the moment the stored values and the schema diverge.
Teams then do one of three things.
They edit in the admin and hope. The field looks empty, so someone retypes the content. The old meta remains. You now have two sources of truth and a site that cannot be rebuilt from the field group.
They write a one-off WP-CLI script. This can work. It is also how a typo in a LIKE query rewrites the wrong keys across every post. Without a preview, a transaction, and a rollback, you find out after editors start ringing.
They leave the schema messy. Fields stay where they were born. Groups accumulate. Templates grow conditionals. The next developer inherits a field map that cannot be explained without a spreadsheet.
None of those is a workflow. They are coping strategies.
A migration has to move both sides
A safe ACF change is not “save the field group”. It is a plan that covers:
- What the schema becomes — name, parent, group, type, location.
- Which stored values must move — posts, terms, users, options, nested rows.
- What templates still call the old name — PHP, blocks,
acf_form()front-end forms. - How you reverse it if the result is wrong.
If you cannot answer those four before you click save, you are guessing.
Preview matters more than cleverness. You need to see how many rows will change, which objects are in scope, and whether a type conversion will drop data. A rename that touches 12 pages is a different job from one that touches 40,000 repeater rows.
Transactions matter because a half-applied migration is worse than no migration. If the schema writes and the meta update fails, you have empty editors and stranded keys. If the meta updates and the schema rolls back, you have the opposite. Both sides have to commit or neither should.
Rollback matters because previews are not production. An editor will save something unexpected. A WPML translation will use a different post ID. A field you thought was unused will appear on an options page. You want a changelog you can read, a backup you can restore, and a window in which reversing the run is a button, not a forensic exercise.
Compatibility is part of the migration
Moving the data is not enough if the theme still calls get_field('old_name'). Front-end forms using acf_form() will post to the old key. REST consumers may still send the previous shape.
The honest options are:
- Update every caller in the same release as the migration.
- Generate a compatibility shim so old calls keep resolving while you catch up.
- Scan the theme for stale field names before you run anything.
Doing none of those means the migration “worked” in the database and failed in production. Doing all of them by hand on a large theme is slow and easy to miss. Scanning PHP for field references and emitting shims is the unglamorous half of the job, and it is the half most one-off scripts skip.
What FieldCraft is for
FieldCraft exists because this work is repetitive, dangerous, and poorly served by dragging fields in ACF itself. It is a paid WordPress admin plugin for ACF Pro 6.0 or later. It will not initialise on ACF Free.
The point is not a prettier field editor. The point is to plan a schema change and a stored-value migration together, show the impact, then write both inside a transaction with a backup and a changelog.
Typical runs:
- Rename a field and migrate every meta key that used the old name.
- Move a populated field between groups without emptying the editor.
- Wrap loose fields into a group.
- Move nested or cross-repeater rows.
- Convert a field type where the conversion is actually supported, and refuse it where it is not.
- Copy or move a section or flexible layout between pages, with a collision preview on both sides.
Destructive work has a preview, a 24-hour rollback window, and a human-readable record of what moved. Empty groups can be archived rather than deleted by accident. Playbooks exist for refactors you will run more than once, with an optional second administrator approval.
That is the opposite of a one-off SQL update.
What FieldCraft is not
It is not a replacement for ACF. You still design fields in ACF Pro.
It is not Nought Sync. FieldCraft restructures fields and values on one site. Sync is how selected WordPress changes move between local, staging and production. Mixing those two jobs is how staging schema overwrites live content.
It is not a licence to skip backups. FieldCraft wraps its own runs. You still want a site-level backup plane before you attempt anything large. If you already run Nought Backup, use it. If you do not, use whatever off-site backup you trust, then run the field migration.
It does not work without ACF Pro. Activation is blocked if ACF is missing.
A working order for a live site
If you need to change ACF architecture on a site that already has content, do it in this order.
Inventory. List the field, its group, its locations, and whether Local JSON is in play. Search the theme for the field name. Note WPML or Polylang if translations exist.
Copy production down. Do not invent the migration on live. Pull a current database to local or staging. Confirm the empty-field symptom reproduces.
Preview the run. Count the objects and rows. Read the collision list. If the number surprises you, stop and find out why.
Commit in a transaction. Schema and values together. Confirm a sample of posts in the editor and on the front end.
Check callers. Templates, blocks, forms, REST. Apply shims or ship the template updates in the same release.
Keep the changelog. If an editor reports a blank field tomorrow, you want to reverse the run, not reconstruct it from memory.
Only then promote. Use environment sync as a separate, selected step. Do not treat a field-group JSON commit as a content migration.
This is slower than dragging a field. It is faster than restoring from backup because someone renamed hero_title on a Friday.
The underlying rule
ACF field groups are not your content. They are a map to your content. When the map changes, the stored values have to change with it, or you have a site that looks empty and a database that is not.
Treat field moves as migrations. Preview them. Run them as one write. Keep a way back. If your tooling cannot do that, do not use the ACF UI as if it can.