Complete ACF / SCF to Field Forge Migration Guide

This is the complete, step-by-step guide to migrating from Advanced Custom Fields (ACF) or Secure Custom Fields (SCF) to Field Forge. It covers preparation, backup, installation, the import process, verification, and deactivation. Plus troubleshooting for common issues and edge cases.

The good news: because Field Forge includes a full ACF compatibility layer, migration does not require rewriting any theme code. Your get_field(), have_rows(), and acf_register_block_type() calls keep working after migration. Most sites complete the process in 30–90 minutes.

---

Part 1: Before you start

Why migrate?

Before investing time in migration, make sure the change is worth it. Reasons to migrate from ACF or SCF to Field Forge:

• Performance — Field Forge’s custom table storage is 3–10x faster on sites with 1,000+ posts or complex repeaters
• AI schema generation — unique to Field Forge, saves 80% of time on field group setup
• Headless WordPress tooling — TypeScript and GraphQL auto-generation
• Price — Field Forge Personal $35/yr vs ACF Pro $49/yr; Agency $169 vs ACF Agency $249
• ACF/SCF fork uncertainty — escape the WP Engine / WordPress.org drama with a plugin that isn’t involved
• Schema versioning — never lose a field group change; one-click rollback
• Modern architecture — Field Forge was built for WordPress in 2026, not 2016

If none of these apply to your situation, stay on ACF or SCF. Migration has a cost (time, testing, risk) and you should only migrate if the benefits outweigh that cost.

Compatibility check

Before migrating, verify that your ACF-specific code won’t hit edge cases in Field Forge’s compat layer.

Things that work out of the box:

• get_field(), the_field(), get_fields(), get_field_object(), get_field_objects()
• update_field(), delete_field()
• have_rows(), the_row(), get_row(), get_row_index(), get_row_layout()
• get_sub_field(), the_sub_field(), update_sub_field()
• acf_register_block_type() (Gutenberg PHP blocks)
• get_field('name', 'options') and get_field('name', 'option') (options pages)
• get_field('name', 'user_123') (user custom fields)
• format_value parameter across all functions
• All 32 field types (text, image, repeater, flexible content, relationship, etc.)

Things that need adjustment:

• ACF-specific hooks like acf/load_field, acf/save_post, acf/format_value/type=text — these have Field Forge equivalents (fieldforge/load_field, etc.) that your code will need to be updated to use. Field Forge’s compat layer does NOT forward ACF hooks to its own hook system.
• Custom field type extensions registered via ACF’s hook system — these need to be re-registered using Field Forge’s field type registration API
• Internal ACF PHP classes accessed directly (e.g., ACF\Admin\AdminFields) — these don’t exist in Field Forge
• ACF’s internal JavaScript API (acf.addAction(), etc.) — Field Forge has its own JS API

For 95% of sites, none of the above matters. Themes typically only use the template functions, not the internal APIs.

How to audit your code:

Run a grep across your theme and custom plugin files:

# Find all ACF template function calls (should work)
grep -r "get_field\|have_rows\|the_sub_field\|acf_register_block_type" wp-content/themes/your-theme/

# Find ACF-specific hooks (need adjustment)
grep -r "add_action.*'acf/\|add_filter.*'acf/" wp-content/themes/your-theme/

# Find ACF internal class usage (needs rewrite)
grep -r "\\\\ACF\\\\\|use ACF" wp-content/themes/your-theme/

If the first grep returns results and the second two are empty, you’re in the clear — direct migration works. If the second or third returns results, plan for additional code updates after migration.

---

Part 2: Backup (critical)

Full database backup

Always backup before migration. This is non-negotiable.

Via your host’s tool:

Most managed WordPress hosts (Kinsta, WP Engine, SiteGround, Cloudways, etc.) have one-click database backup. Use it.

Via WP-CLI:

wp db export backup-before-fieldforge-$(date +%Y%m%d).sql

This creates a SQL dump of your entire database. Keep it somewhere safe (download to local, upload to S3, etc.). If migration goes wrong, you can restore from this dump.

Via plugin:

UpdraftPlus, BackupBuddy, BackWPup, or similar. Run a full backup — database AND files — before proceeding.

File backup

Back up your entire wp-content/ directory too. If you’re using ACF’s Local JSON feature, the JSON files are in wp-content/themes/your-theme/acf-json/.

Staging environment (recommended)

If possible, do the migration on a staging environment first. Clone your production site to staging, run the migration, verify everything works, then repeat on production. Most managed hosts offer one-click staging cloning.

If you don’t have staging, do the migration during low-traffic hours.

---

Part 3: Install Field Forge

Download the plugin

Go to Field Forge pricing and purchase a license. You’ll receive a download link for the Field Forge plugin ZIP file.

Or install the free version from WordPress.org:

1. WordPress admin → Plugins → Add New
2. Search “Field Forge”
3. Install and activate

Note: the free version covers the core migration features. Paid plans unlock AI generation, TypeScript, GraphQL, and some advanced field types.

Upload and activate

1. WordPress admin → Plugins → Add New → Upload Plugin
2. Choose the Field Forge ZIP file
3. Install Now → Activate Plugin

Field Forge now appears in your WordPress admin menu. ACF (or SCF) is still active — you’ll deactivate it later.

Activate your license

If you purchased a paid plan, activate the license:

1. Field Forge → Settings → License
2. Paste your license key
3. Click Activate License

You’ll get a confirmation that the license is valid.

Confirm Field Forge and ACF don’t conflict

Field Forge’s ACF compatibility layer is smart about running alongside ACF. When both plugins are active:

• ACF continues to serve all template function calls (get_field(), etc.)
• Field Forge does NOT override ACF’s functions (because ACF is still the authoritative source)
• Field Forge registers its own admin screens alongside ACF’s
• You can configure Field Forge field groups without affecting ACF

This means there’s no conflict during migration. You can work in both plugins’ admin screens simultaneously.

---

Part 4: Run the import

Open the import tool

1. WordPress admin → Field Forge → Tools → Import
2. You’ll see verified ACF/SCF import actions, plus any beta/manual source detections the site exposes for planning
3. Click Import from Advanced Custom Fields (or Secure Custom Fields)

Configure import options

The import configuration screen offers several options:

• Import field groups — imports field group definitions from ACF to Field Forge (required)
• Import field values — migrates all existing field values from wp_postmeta to Field Forge’s custom table (recommended)
• Import options page values — migrates options page data (if you use ACF Options Pages)
• Batch size — posts per request (default 50, lower for slow hosts, higher for fast hosts)
• Skip empty field values — don’t migrate fields with empty values (saves time and storage)
• Dry run — simulate the migration without making changes (good for previewing)

Start with defaults. If the migration hits errors, adjust options and re-run.

Run the import

Click Start Import. A progress bar appears showing:

• Current phase (field groups → field values → options pages → verification)
• Posts processed / total posts
• Time elapsed / estimated time remaining
• Errors (if any)

The import runs in batches of 50 posts per AJAX request. The batching prevents PHP timeouts on large sites and provides visible progress.

Expected time

• <100 posts: 1–2 minutes
• 100–1,000 posts: 3–10 minutes
• 1,000–10,000 posts: 15–45 minutes
• 10,000+ posts: 45 minutes to 2 hours

During the import, don’t close the browser tab. If you accidentally close it, the import pauses; reopen the import page and click Resume Import.

---

Part 5: Verify the migration

Automatic verification

After the import completes, Field Forge runs automatic checks:

• Field group count — number of migrated groups matches number of source groups
• Field value count — spot-checks on random posts to confirm values migrated
• Schema integrity — verifies field definitions are valid
• Options pages — confirms options page data is accessible

You’ll see a green checkmark next to each verification step, or a yellow/red alert if something needs attention.

Manual verification

Don’t rely only on automatic checks. Spot-check important pages:

1. Check a typical post with custom fields

Go to WordPress admin → Posts → pick a post that uses custom fields → scroll to the Field Forge metabox → verify field values match what’s in the ACF metabox above.

2. Check a page with flexible content

If you use flexible content fields, check a page with multiple layouts. All layouts should appear in the Field Forge metabox with correct field values.

3. Check a page with repeaters

If you use repeater fields, verify all rows are present with correct sub-field values.

4. Check options pages

Go to any options page (Site Settings, Header Settings, etc.) — values should appear both in ACF’s options page view AND in Field Forge’s version.

5. Check the frontend

Load the homepage and several key pages in a browser. ACF is still active at this point, so frontend rendering still comes from ACF. Confirm nothing has broken during the migration process.

If verification fails

If any check fails:

1. Don’t panic. ACF is still active; your site is still serving content normally.
2. Check the error log. Field Forge logs detailed errors in WordPress’s error log or in the Field Forge admin at Tools → Logs.
3. Re-run the import. Sometimes transient errors (timeouts, temporary database issues) resolve on retry.
4. Check for specific field types that failed. Field Forge’s log identifies which field types had issues.
5. Contact support — [email protected] with details about the failure.

---

Part 6: Deactivate ACF (the critical step)

This is the moment of truth. Deactivating ACF activates Field Forge’s compatibility layer — all get_field() calls from your theme will now resolve to Field Forge’s storage instead of ACF’s.

Before you deactivate

• Verify everything is migrated (Part 5)
• Confirm frontend looks correct with ACF still active
• Have your backup ready (Part 2)
• Pick a low-traffic moment if this is a production site

Deactivate ACF

WordPress admin → Plugins → Installed Plugins → Advanced Custom Fields → Deactivate

Do NOT click “Delete” yet — we want ACF available as a fallback if something goes wrong.

What happens immediately

The moment ACF is deactivated:

• ACF’s template functions (get_field, etc.) stop being registered by ACF
• Field Forge’s compatibility layer detects this and registers its own implementations
• Template calls now resolve to Field Forge’s storage
• Field Forge’s admin screens take over the “Custom Fields” navigation

Test the frontend

Immediately reload the frontend:

1. Homepage — does it look correct?
2. A page with flexible content — do all sections render?
3. A page with a repeater — do all rows display?
4. Options pages — do global settings appear (site name, social URLs, etc.)?
5. A Gutenberg PHP block (if you use acf_register_block_type()) — does it render?

If everything looks correct, the migration is successful. Celebrate.

If something is broken, go to Part 8 (Troubleshooting) below.

---

Part 7: Cleanup and optimization

Delete ACF (after 1 week)

Wait 1 week with Field Forge active before deleting ACF entirely. This gives you time to discover any edge cases that weren’t caught in immediate verification. If issues come up, reactivate ACF as a fallback while you debug.

After 1 week of stable operation:

1. WordPress admin → Plugins → Installed Plugins
2. Advanced Custom Fields → Delete
3. Confirm deletion
4. ACF is gone from your site

Optional: clean up wp_postmeta

After migration, ACF’s data is still sitting in wp_postmeta (Field Forge’s migration is non-destructive — it copies data, doesn’t delete from source). This extra data takes up space but doesn’t harm anything.

If you want to clean it up:

DELETE FROM wp_postmeta
WHERE meta_key LIKE '_%'
AND meta_key IN (
    SELECT DISTINCT meta_key
    FROM wp_postmeta
    WHERE meta_key LIKE '_%'
);

WARNING: This SQL is approximate and dangerous. Only run it if you’re comfortable with database operations AND have a recent backup. Field Forge’s support can help with a safer cleanup query tailored to your specific field groups.

Most sites don’t bother with this cleanup — the extra storage is negligible.

Optimize Field Forge settings

Now that you’re fully on Field Forge, take advantage of its features:

1. Enable Local JSON Sync — save field groups as JSON files in your theme for git versioning (Field Forge → Settings → Local JSON)
2. Enable object cache — if you have Redis or Memcached, Field Forge automatically uses it
3. Run batch load on archive pages via custom template tags for even faster performance
4. Try AI schema generation — the next field group you create, try the AI generator instead of building manually
5. Generate TypeScript types — if you have a headless frontend, download the .d.ts files from Field Forge’s admin

---

Part 8: Troubleshooting

“Missing field values” after deactivating ACF

Symptom: A post that had custom field values in ACF appears empty in Field Forge after ACF is deactivated.

Cause: The field value didn’t migrate during the import. This can happen if:

• The field was added to ACF after the last time a post was saved
• The field has an unusual storage format (very rare)
• The import was interrupted before this specific post was processed

Fix:

1. Reactivate ACF (data is safe)
2. Go to Field Forge → Tools → Import
3. Re-run the import with “Resume” or “Full Rerun” option
4. The importer will re-check all posts and pick up any missed values
5. Deactivate ACF again and re-verify

“Broken template” after deactivating ACF

Symptom: A template that used to render correctly now throws a PHP error or shows unexpected content.

Cause: The template is using an ACF-specific function or hook that Field Forge’s compat layer doesn’t cover.

Fix:

1. Reactivate ACF
2. Check PHP error logs for the specific function / hook that failed
3. Identify which ACF-specific API the template is using
4. Update the template to use Field Forge’s equivalent
5. Deactivate ACF again

Most common culprits:

• acf_add_local_field_group() — use fieldforge_register_field_group() instead
• acf_form() — use Form Forge or a different form builder
• Custom field types registered via acf/include_field_types hook — re-register via fieldforge/field_types/register filter

“Slower performance after migration”

Symptom: Pages load slower after switching to Field Forge.

Cause: Rare but possible. Field Forge’s custom table storage should be faster, not slower. If you see slower performance:

• Object cache isn’t configured correctly — Field Forge falls back to database queries
• WordPress’s WP_DEBUG is enabled with a large logging file
• A different plugin is causing the slowdown (coincidental timing)

Fix:

1. Check your object cache plugin is active and working
2. Disable WP_DEBUG and WP_DEBUG_LOG in production
3. Run Field Forge → Tools → Performance Test to benchmark specific pages
4. Contact support with timing details

“Migration seems to have skipped options pages”

Symptom: Options pages values appear empty or default after migration.

Cause: ACF stores options page values with a different key prefix than post field values. The importer needs to handle both cases.

Fix:

1. Go to Field Forge → Tools → Import
2. Click Re-import Options Pages
3. This re-runs just the options page migration

“Repeater rows are in the wrong order”

Symptom: Repeater fields migrated, but the rows appear in a different order than they were in ACF.

Cause: Rare race condition during the import where the row_index wasn’t correctly set.

Fix: Contact support with the specific field group name. This is typically a one-time fix with a SQL update.

---

Part 9: Rollback (if you need it)

Quick rollback

If the migration goes wrong and you need to return to ACF:

1. Reactivate ACF (Plugins → Installed Plugins → ACF → Activate)
2. Deactivate Field Forge (Plugins → Installed Plugins → Field Forge → Deactivate)
3. ACF’s template functions re-register
4. Your site returns to serving data from wp_postmeta (ACF’s storage)
5. Everything works as it did before the migration attempt

Field Forge’s migration is non-destructive — ACF’s data is still in place. Rollback is always possible as long as you haven’t deleted ACF.

Full rollback to pre-migration state

If you want to completely undo the migration and remove Field Forge:

1. Reactivate ACF
2. Deactivate Field Forge
3. Field Forge → Settings → Delete All Data (removes Field Forge’s custom table, revisions, JSON files)
4. Deactivate and delete Field Forge
5. Your site is back to exactly where it was before migration

---

Frequently asked questions

How long does a typical ACF migration take?

30–90 minutes for most sites. Larger sites (10,000+ posts) may take 2+ hours.

Will my rankings drop during migration?

No. Migration doesn’t change URLs, content, or meta data that Google sees. Field Forge migrates the storage layer only.

Can I run ACF and Field Forge indefinitely?

Technically yes during migration, but not as a long-term production setup. Running both means duplicate admin UIs and configuration confusion.

What about ACF Pro features like Repeater and Flexible Content?

Field Forge’s paid plans include all ACF Pro features. Repeater, Flexible Content, Group, Clone, Options Pages, Gallery, PHP Blocks — all work after migration.

Do I need to rewrite my theme code?

No. Field Forge’s ACF compatibility layer means existing code keeps working.

What if I have custom ACF field types from third-party plugins?

Custom field types registered via ACF’s hook system need to be re-registered for Field Forge. Contact support for help with specific cases.

Can I migrate back from Field Forge to ACF later?

Yes. Field Forge’s data export lets you export field groups in ACF-compatible format. Import into ACF, deactivate Field Forge. Your site keeps working.

Is the migration free?

Field Forge’s free version on WordPress.org includes the migration tools. You only need a paid license for AI features, TypeScript/GraphQL generation, and some advanced field types.

Does migration work for SCF too?

Yes. SCF is a fork of ACF with the same data format. The ACF importer handles both.

---

Ready to migrate?

Get Field Forge — from $35/year →

14-day refund. Free version includes migration tools. Priority support during migration.

Questions before you start? Contact our migration support team →