
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-jsonfolder exists in your active child theme directory (chmod 775). Add theacf/settings/save_jsonandacf/settings/load_jsonfilters tofunctions.phpusingget_stylesheet_directory()instead ofget_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:
- Backup JSON folder
- Delete stale
.jsonfiles - Commit fresh JSON to Git repo (if using Git)
- Open ACF → Field Groups
- Click Sync available fields
- Re-save each field group once
- 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-jsonfolder exists in theme - Permissions set (775)
- Correct
save_jsonandload_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.

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.


