Skip to main content

Fix ACF JSON Sync Not Working (Full Guide + Best Practices 2026)

Fix ACF JSON sync not showing, not updating, or reverting changes. Step-by-step solutions, code snippets, and workflow for agencies and freelancers working with Advanced Custom Fields.

Faisal Yaqoob
6 min
#ACF#Advanced Custom Fields#WordPress#ACF JSON#Web Development
Fix ACF JSON Sync Not Working (Full Guide + Best Practices 2026) — Troubleshooting guide thumbnail

ACF Local JSON sync keeps custom field definitions version-controlled in your theme files. When the "Sync Available" tab disappears or changes revert after deployment, it typically stems from directory path filters pointing to a parent theme, Unix permissions blocking file writes, or timestamp drift between the MySQL database and JSON files.

Quick Answer: How to Fix ACF JSON Sync Not Working

To restore ACF Local JSON sync: Ensure a writable acf-json folder exists in your active child theme directory (chmod 775). Add the acf/settings/save_json and acf/settings/load_json filters to functions.php using get_stylesheet_directory() instead of get_template_directory(). If the sync tab is still missing, resave any field group once in the WordPress dashboard to force ACF to index the folder.

Why ACF JSON Sync Breaks

Common triggers:

  • Fields not showing in sync tab
  • Sync button missing after migration
  • Fields revert after saving
  • JSON folder ignored by ACF
  • UI changes not reflected in templates
  • Theme switched or using child theme
  • Permissions or version mismatch

Quick Fix Checklist

Run through these first:

  • Folder exists: /acf-json/
  • Folder writable (775 recommended)
  • Same ACF version across environments
  • Save field group once manually
  • Clear WordPress cache / OPcache
  • Remove old JSON files and refresh ACF field groups page
chmod -R 775 wp-content/themes/your-theme/acf-json

ACF JSON Path Setup

Confirm the save + load locations. Add to your theme/plugin:

// Save JSON
add_filter('acf/settings/save_json', function ($path) {
  return get_stylesheet_directory() . '/acf-json';
});

// Load JSON
add_filter('acf/settings/load_json', function ($paths) {
  unset($paths[0]);
  $paths[] = get_stylesheet_directory() . '/acf-json';
  return $paths;
});

If using a child theme

return get_stylesheet_directory() . '/acf-json'; // child theme
// instead of get_template_directory()

Full Fix Workflow

Recommended process for clean sync:

  1. Backup JSON folder
  2. Delete stale .json files
  3. Commit fresh JSON to Git repo (if using Git)
  4. Open ACF → Field Groups
  5. Click Sync available fields
  6. Re-save each field group once
  7. Clear cache + refresh pages with ACF data

Verification snippet:

var_dump(get_stylesheet_directory() . '/acf-json');

If it prints expected path, the theme is pointing correctly.

Environment Version Fix

Always match versions:

Env ACF Version
Local ✅ same version
Staging ✅ same version
Production ✅ same version

Mismatched ACF versions cause sync issues.

Best Practices

  • One source of truth (dev)
  • JSON folder in Git (always commit changes)
  • Avoid editing fields in production
  • Always "Save Field Group" after deploy
  • Keep folder name exactly acf-json

Elementor / Bricks Builder Note

After syncing:

  • Elementor: Regenerate CSS + Data → Clear cache
  • Bricks: Rebuild Cache
  • Block Editor: Clear WP transient cache

Common Issues Table

Issue Fix
JSON folder exists but sync missing Check path filters / permissions
Fields revert after updating Clear cache + save group again
ACF data not showing on front end Template uses wrong key or theme cache
Site migrated; fields missing Copy JSON + sync + re-save
Two ACF JSON folders Remove duplicates / unify source

Example Folder Structure

wp-content/
  themes/
    your-theme/
      acf-json/
        group_header.json
        group_footer.json
        group_home.json

Testing Snippet

echo get_field('hero_title') ?: 'ACF field empty – check sync';

ACF JSON Sync Checklist

  • acf-json folder exists in theme
  • Permissions set (775)
  • Correct save_json and load_json
  • Same ACF version everywhere
  • Field groups synced + re-saved
  • Caches cleared (WP + server)
  • Only one JSON sync location

Need Professional ACF Theme & Block Engineering?

I build and fix bespoke ACF architectures:

  • Broken ACF Local JSON sync & migration conflicts
  • Complex Repeater & Flexible Content modular layouts
  • Hybrid ACF + Gutenberg custom block development
  • Pixel-perfect Figma to ACF Pro theme conversions

Explore my dedicated custom ACF WordPress theme developer services for fixed-scope builds and clean, bloat-free PHP architectures — or discuss your project for same-day triage.

Frequently Asked Questions

Why is the ACF Sync Available tab not showing?

The Sync Available tab only appears when the JSON file in acf-json has a newer modified timestamp than the field group stored in your WordPress database. If the database copy was saved more recently, or if acf/settings/load_json points to the wrong theme directory, ACF hides the sync option.

Should I use get_stylesheet_directory() or get_template_directory() for ACF JSON in a child theme?

Use get_stylesheet_directory() in child themes so ACF reads and writes to the child theme's acf-json folder. get_template_directory() points to the parent theme, which causes your field group JSON files to be missed or overwritten on parent theme updates.

Why do ACF fields revert after deployment or migration?

If you deploy new acf-json files without clicking Sync in Custom Fields → Field Groups, WordPress still reads the older field definitions from the database. Always run ACF sync (or acf_import_field_group in WP-CLI) after pulling theme changes.

Should I commit the acf-json folder to Git?

Yes. Tracking acf-json/*.json in Git keeps field definitions versioned alongside your PHP templates so staging and production stay in sync without exporting and importing database dumps.

Professional portrait of Faisal Yaqoob, senior WordPress developer with 10+ years experience

Faisal Yaqoob

Senior WordPress Developer & Specialist

Senior WordPress specialist with 10+ years experience engineering custom ACF Pro themes, Core Web Vitals speed optimizations, WooCommerce stores, and white-label agency builds.

10+ Years500+ Projects100+ Agencies