This recipe provides a detailed, cautious migration process with checklists and verification steps. Follow it in order to ensure a smooth transition.
Pre-Migration Checklist
Before you begin, complete every item on this list:
| Step | Action | Done? |
|---|---|---|
| 1 | Create a full site backup (files + database) | |
| 2 | Set up a staging/test site and perform the migration there first | |
| 3 | Document your current ACF field groups (screenshot or export) | |
| 4 | Note any PHP-registered field groups in your theme’s functions.php | |
| 5 | Check for plugins that depend on ACF (some plugins bundle their own ACF fields) | |
| 6 | Install Field Forge on your test site (do NOT deactivate ACF yet) | |
| 7 | If migrating field values, activate a Field Forge PRO license | |
| 8 | Verify your PHP memory limit is at least 256M and max_execution_time is at least 300 |
Step 1: Detect ACF Data
- Go to Field Forge > Migration
- Click Detect ACF Data
- Review the scan results:
– Number of posts with ACF data
– Total field values to migrate
- Take a screenshot or note these numbers — you will use them to verify migration completeness later
Step 2: Import Field Groups
- Click Import Field Groups
- Wait for the import to complete
- Verify the results:
– Open 2-3 field groups and check that all fields, settings, and location rules match your ACF configuration
– Pay special attention to complex fields: Repeaters, Flexible Content, and Groups should have all their sub-fields intact
- If anything looks wrong, you can delete the imported groups and re-run the import — it reads from ACF’s data, which is unchanged
Step 3: Migrate Field Values (PRO)
- Back on Field Forge > Migration, click Import Field Groups with Values
- A progress bar appears showing batch processing
- For large sites, the migration runs in the background — you can safely close the browser tab
- Wait for the completion notice (check back if you closed the tab)
- Note the final count: number of posts processed and values migrated
Step 4: Post-Migration Verification
Perform these checks before deactivating ACF:
| Check | How to verify | Expected result |
|---|---|---|
| Field groups exist | Field Forge > Field Groups | Same number of groups as in ACF |
| Fields appear on posts | Edit a post that had ACF data | Metabox with fields appears below editor |
| Data is populated | Check the fields on several posts | Values match what was entered in ACF |
| Repeater data intact | Open a post with a repeater | All rows present with correct data |
| Flexible Content intact | Open a post with flexible content | All layouts present in correct order |
| Options page data | Visit the options page | All global values present |
| Frontend display | View the site in a browser | Pages look identical to before migration |
get_field() works | Test pages that use field data | No errors, correct values displayed |
have_rows() works | Test pages with repeaters | Loops function correctly |
Step 5: Deactivate ACF
- Once all checks pass, go to Plugins
- Deactivate Advanced Custom Fields PRO
- Refresh the frontend and check several pages — everything should continue working because Field Forge provides all the same functions
- Check the admin area — all field groups should remain visible and functional
Step 6: Verify Everything Works Without ACF
- Test every page template that uses custom fields
- Test every form, repeater, and flexible content section
- Check options pages and site-wide settings
- Test on multiple devices (desktop, tablet, mobile)
- Ask another team member to spot-check key pages
Common Issues and Fixes
| Issue | Cause | Fix |
|---|---|---|
| Fatal error after deactivating ACF | A plugin depends on ACF directly (not through get_field()) | Reactivate ACF, identify the dependent plugin, and contact its author for Field Forge compatibility |
| Some fields show empty | Field values were not migrated (free version) | Upgrade to PRO and run the value migration |
| Repeater rows in wrong order | Rare edge case with deeply nested data | Re-run the migration; if it persists, contact support |
| Nested Repeater rows inside Flexible Content duplicate after drag-and-save | Older builds re-indexed the parent Flexible Content row when sorting the nested Repeater, then read the nested records from the wrong parent record | Update Field Forge, hard-refresh the editor, re-order the nested rows once, and save. Current builds re-index the active Repeater only and read nested records by their direct parent ID. |
| Nested Group / Repeater / Flexible Content values are missing | Old ACF databases can contain duplicate field-group posts with the same key/title; an empty duplicate can hide the populated group during import | Update Field Forge and re-run the migration. Current builds de-duplicate ACF groups by key/title and keep the version with the most direct child fields before importing values. |
| Conditional logic not hiding fields | Top-level rules: confirm “Conditional Logic” is toggled on in the field’s settings, the rule’s trigger field has a value, and the operator/value pair matches your data. Nested rules (inside Repeater / Group / Flex layouts) are stored but not yet evaluated. | Re-open the field group editor, expand the affected field, and check that the rule reads the correct field name. For nested cases, move the rule to a top-level field that controls the parent compound’s visibility. |
| Options page missing | Options pages require PRO | Activate PRO license, then re-run migration |
| Frontend layout broken | Theme relies on ACF-specific hooks | Check if the theme uses acf/ hooks and switch to fieldforge/ equivalents |
| JSON export files referencing ACF keys | Old Local JSON files from ACF | Delete the old acf-json/ files in your theme and re-save field groups so Field Forge regenerates fresh files in fieldforge-json/ (the default sync folder) |
—