Troubleshooting Guide

This section covers the most common issues you may encounter with Field Forge and how to resolve them. For each issue, we describe the symptoms, likely causes, and step-by-step fixes.

Tooltip Help Opens the Homepage Instead of the Article

Symptoms: Clicking the small ? help icon in Field Forge admin opens the Field Forge landing page or docs homepage instead of the specific article for that setting. Fix: Update Field Forge to the current build. Admin help links now route to exact User Guide or Developer Guide section URLs. If a cached admin page still has the old link, hard-refresh the page once.

Forge Suite Deactivate on a Clone Affects Another Site

Symptoms: You cloned or restored a WordPress site, then clicked Forge Suite > Deactivate on the clone. Another site using the same license appeared to lose PRO or Connect state. Cause: Older builds trusted the Freemius install id stored in fs_accounts. A cloned database can carry the original site’s install id and URL, so even an install-scoped Freemius deactivation can target the original remote install. Fix: Update Field Forge to the latest build. Forge Suite now compares the stored Freemius site URL with the current WordPress site_url() / home_url() before any remote deactivation. If the state belongs to another site, it skips the remote Freemius call and only clears local license state for the current WordPress install. Reconnect the clone through Field Forge > License > Connect to Avakode when you want it to be licensed again.

Fields Not Showing on the Post Editor

Symptoms: You created a field group, but the fields do not appear when you edit a post or page. Possible causes and fixes:

Location rules do not match the post. Open the field group and check the Location Rules section. Verify that the conditions match the post you are editing. For example, if the rule says “Post Type is equal to Product” but you are editing a Page, the fields will not appear.
The field group is set to Inactive. In the field group list, check that the Status column shows “Active.” If it says “Inactive,” open the field group and change its status.
Another plugin is hiding the metabox. Some page builder plugins or admin cleanup plugins hide metaboxes. Check Screen Options (top-right corner of the edit screen) and make sure your field group metabox is checked.
The field group has no fields. An empty field group with zero fields will not display a metabox. Open the field group and add at least one field.
Cache issue. If you just created the field group, try refreshing the post editor page. In some hosting environments, object caching can delay the appearance of new metaboxes.

get_field() Returning Null

Symptoms: Your theme template uses get_field('field_name') but it returns null or an empty value, even though data was entered in the editor. Possible causes and fixes:

Wrong field name. The name passed to get_field() must match the field Name (slug), not the Label. Open the field group editor and check the Name column. For example, if the label is “Hero Title” but the name is hero_title, use get_field('hero_title').
Missing post ID. If you call get_field() outside The Loop (for example, in a header or footer template), you must pass the post ID explicitly: get_field('hero_title', $post_id). Without the second parameter, it defaults to the current post in The Loop, which may not exist in your context.
Using options page data without ‘options’. For options page fields, you must pass 'options' as the second parameter: get_field('site_phone', 'options'). Without it, Field Forge looks for the field on the current post and finds nothing.
Field Forge is deactivated. If Field Forge is not active and your theme does not have a fallback, get_field() will be undefined and cause a fatal error (or return null if another plugin provides a stub). Check that Field Forge is activated in Plugins.
Data was entered with ACF but not migrated. If the data was originally saved by ACF and you have not run the migration, Field Forge’s tables will be empty. Go to Field Forge > Migration and import the values.
ACF is active during a LangForge options-page check. When ACF owns get_field(), Field Forge now bridges empty ACF option reads to the same language-aware Field Forge options table fallback used by the ACF compatibility layer. This is intended for migration/QA windows where ACF, Field Forge, and LangForge are active together.

Edits to a Field Inside a Group Do Not Save

Symptoms: You change a text, textarea, or WYSIWYG value that sits inside a Group field, click Update, and the value reverts to the previous content on reload. Other fields on the same post save normally. Fields outside the Group save normally. Why it happens: This was a regression specific to Groups whose data was imported from ACF (or migrated from a previous plugin) and therefore stored hierarchically — the group itself occupies one row in Field Forge’s value table and each sub-field is linked by the group’s record ID. The admin form sub-fields in that structure submitted under a POST key that Field Forge’s save handler did not read, so sub-field edits were silently dropped. Groups that were never touched by the ACF import kept working because they used the legacy flat storage path, which the save handler did read. What the current version does: The save handler now recognises hierarchical group sub-fields and routes them through the same validator + storage path as any other field. The fix covers text, textarea, WYSIWYG, number, select, and the other “simple” field types inside Groups, as well as Groups nested inside Repeaters and Flexible Content layouts. Recovering already-lost edits: Edits made before the fix were never persisted — there is no record of them to recover. Re-enter the content and click Update; the value will save correctly.

Values Accumulate Backslashes on Every Save

Symptoms: A field with quotes in its value (most often an iframe embed, a WYSIWYG block containing data-* attributes, or a textarea with raw HTML) starts showing extra backslashes each time the post is saved: width="900" becomes width="900", then width=\"900\", and so on — up to a dozen or more backslashes after several rounds of editing. Re-editing the field, creating translations, or using third-party “duplicate post” tools accelerates the accumulation. Why it happens: WordPress automatically adds a backslash before every quote in form data. Field Forge’s save handler used to store the received value without stripping those added slashes, so each save round preserved the previous slashes and added a new layer on top. Values that never contained quotes were unaffected. What the current version does: The save handler unescapes the incoming form data once at the top, so the stored value matches what the user actually typed. Future saves no longer add slashes. Cleaning up already-corrupted values:

Open each affected post in the admin. If the value displays with visible backslashes before the quotes, the stored content is corrupted
In the field editor, manually strip the backslashes and save once — the corrected value will persist going forward
For bulk repair on a site with many corrupted rows, a WP-CLI script can iterate stripslashes() over values in wp_fieldforge_values until the value stabilises. Restrict the pass to text-like field types (wysiwyg, textarea, text, url, email) — binary identifiers and color values must not be touched. Contact support if you need the exact query

ACF Migration Incomplete or Stuck

Symptoms: The migration progress bar stops partway, or not all posts have their data after migration. Possible causes and fixes:

PHP timeout. Large sites may hit the PHP execution time limit. The migration runs in batches of 50 posts to avoid this, but very slow servers may still time out. Increase max_execution_time in your PHP settings (or php.ini) to at least 300 seconds, then restart the migration.
Memory limit. Posts with many complex fields (nested repeaters, large galleries) can consume significant memory. Increase memory_limit to at least 256M in your PHP settings.
ACF was deactivated before migration completed. ACF must remain active during the entire migration process because Field Forge reads data through ACF’s functions. Reactivate ACF and restart the migration.
Background processing failed silently. Check the Field Forge migration status page for error messages. If the background process was interrupted (server restart, hosting maintenance), click “Resume Migration” to continue from where it left off.
Partial migration is expected on Free. The free version only migrates field group definitions, not field values. If your posts have the correct fields but no data, upgrade to PRO to migrate values.
Local QA bootstrap mismatch. On local Forge QA sites that define FORGE_SKIP_LICENSE_REVALIDATION, either forge_e2e_plan=pro or a valid fieldforge_license_data['plan']='pro' local license record unlocks value migration. The same local constant also puts Freemius into anonymous mode for Field Forge admin requests, so a fresh QA site should not be blocked by the Freemius opt-in screen before opening Field Forge pages.

Local JSON Not Syncing

Symptoms: You or your developer made changes to JSON files, but field groups in the database do not update. Possible causes and fixes:

Local JSON is not enabled. Go to Field Forge > Settings and verify that Local JSON Sync is turned on.
Wrong directory path. Field Forge looks for JSON files in the fieldforge-json/ folder inside your active theme (or the custom path if configured). Verify the folder exists and contains .json files. The path is case-sensitive.
File permissions. The web server needs read access to the JSON directory. On most hosts, permissions of 755 for the folder and 644 for files are correct.
Sync notice dismissed. When Field Forge detects updated JSON files, it shows a sync notice in the admin. If someone dismissed the notice without clicking Sync, the changes were not applied. Go to Field Forge > Field Groups and look for any pending sync notifications.
Theme was switched. If the active theme changed, Field Forge looks in the new theme’s directory. Make sure the JSON files exist in the currently active theme.
You are importing ACF Local JSON, not syncing Field Forge JSON. ACF source files belong in acf-json/ and are handled by the ACF migration tool. Field Forge’s own sync files belong in fieldforge-json/.

Options Page Not Appearing

Symptoms: You created an options page, but it does not appear in the WordPress admin sidebar. Possible causes and fixes:

PRO is not activated. Options Pages require a PRO license. Go to Field Forge > License and verify your license is active.
Capability mismatch. If the options page was created with a custom capability, your user account may not have it. Log in as an Administrator to confirm the page exists, then adjust the capability setting if needed.
Menu position conflict. If another plugin or menu item occupies the same position number, the options page may be hidden behind it. Try changing the menu position in the options page settings.
Cache. Some caching plugins or object caches may cache the admin menu. Clear your cache and refresh the admin dashboard.

Options Page Changes Disappear After Save

Symptoms: You open an Options Page (the “Общие” theme settings, a custom Options Page, or any page registered through acf_add_options_page / fieldforge_add_options_page), edit a value or add a new repeater row, click Save, see the green “Options saved” notice, then on reload the form shows the OLD value back. The new repeater row is gone, the changed map link is reverted, the picked Privacy Policy page is empty. Why it happens (any of four root causes, all fixed together in v1.0.10):

Translated language tab read default-language data. The compat layer didn’t honour the LangForge ?lf_lang= admin switcher, so the EN/UZ tab rendered RU values. Editing them then wrote back to the default-language storage and the translated language stayed empty.
Compound sub-field names rejected by the save whitelist. Sub-fields whose name contained an underscore — map_link, privacy_policy, social_name, social_link — were silently dropped from the POST processing because the whitelist split the name on _ and required every piece to be a registered field. Their values never reached the database.
Nested have_rows looked up storage under the wrong prefix. A theme calling have_rows('socials') inside have_rows('common', 'option') searched for keys named just socials instead of common_socials. Frontend rendered an empty section even when the data was correctly saved.
The hidden row count was not updated when you clicked Add Row or Remove Row. The new row’s data was saved, but the count input still said the old number. On re-render, the server iterated for ($i = 0; $i < count) and skipped the new row entirely. The row sat in the database, invisible to both the admin form and the public site.

What the current version does: all four bugs are fixed in v1.0.10. Reads and writes on options pages honour the active language; compound names round-trip through the whitelist via greedy-prefix matching; nested iterations carry the parent field prefix; Add Row / Remove Row reflow indexes and update the count input live so save/reload always reflects what you submitted. If you’re still seeing the symptom after upgrading:

Hard reload the admin page (Cmd+Shift+R / Ctrl+Shift+R) to pick up the new admin.js. The cache buster is automatic when you upload the new file, but a stale browser cache will keep the old behaviour.
Verify your hosting’s PHP OPcache picked up the new PHP files. On Hostinger / LiteSpeed shared hosting, OPcache can hold the old class files for up to an hour after upload. Toggle PHP version in the panel or upload a small script to flush.
If your site uses a translation plugin other than LangForge (WPML, Polylang), the fieldforge/options_post_id filter wired by LangForge won’t fire. Translation plugin compatibility for options pages is on the roadmap; for now, ACF Pro + WPML’s ACFML add-on is the supported stack on those sites.

Repeater Image / Page-Link / Textarea Sub-Fields Show Raw Numeric IDs in the Editor

Symptoms: In a Repeater field on the post edit screen, columns like Image or Image @2x display a plain number (800, 2954) in a text input instead of an image preview with Select / Remove buttons. A URL / Page Link column shows a numeric post ID. A textarea column shows a single-line text input that truncates long content. Cause (fixed 2026-04-24): The Repeater renderer hard-coded every sub-field to render as , ignoring the sub-field’s actual type. Top-level fields of the same types rendered correctly via the type-aware input renderer — only the repeater path skipped the dispatch. Fix: Update Field Forge to the latest version. Repeater sub-fields now dispatch to the same type-aware renderer that top-level fields use: image sub-fields come back with preview thumbnails + Select / Remove buttons, page_link and post_object sub-fields render as dropdowns of published pages+posts, textareas render as multi-line textareas. Save behavior and the HTML input-name scheme are unchanged, so previously edited values remain.

Nested Repeater Inside a Repeater Shows a Number in a Text Input

Symptoms: A Repeater has a sub-field that is itself a Repeater (for example, a yearly Awards block where each year contains a list of individual award items). On the post edit screen the outer rows render correctly, but the nested column displays a plain single-digit or two-digit number in a text input — the number matches the count of inner rows for that outer row. Clicking the “number” does nothing, and there is no way to edit the inner items from the editor. The public front end renders correctly because the read path was never broken. Cause (fixed 2026-04-24): The per-row dispatcher introduced on 2026-04-24 handled the simple sub-field types (image, textarea, page_link, post_object, etc.) but still routed nested compound types — Repeater, Group, Flexible Content — through the fallback text input. The fallback stringified the nested repeater’s row-count value, which is how the digit appeared in place of the real UI. Fix: Update Field Forge to the latest version. The repeater renderer now detects when a sub-field’s type is one of repeater / group / flexible_content and delegates to the shared compound renderer with the nested record id that the value loader stores on every row. Nested repeaters now render their own rows with drag handles, trash buttons, and fully functional sub-field inputs (images, textareas, etc.), and nested groups render their sub-field grids. Save behavior and the HTML input-name scheme are unchanged — existing data becomes editable on the next page load with no data migration required.

Repeater “Add Row” Button Renders Without a Label (Empty Pill at the Bottom of the Repeater)

Symptoms: At the bottom of a Repeater (and of nested Repeaters and Flexible Content blocks) there is an empty rose-outlined oval where the “Add Row” / “Add Layout” button should be. Clicking it still adds a row, but there is no visible label to guide the editor. Cause (fixed 2026-04-24): For repeaters migrated from ACF, button_label is stored as an empty string rather than null. The renderer used $field['button_label'] ?? __('Add Row') to fall back to the default label, but ?? only triggers on null — an empty string passes through, so the button rendered with no text. Fix: Update Field Forge to the latest version. The fallback now uses !empty(...) so both null and empty strings resolve to the default “Add Row” / “Add Layout” label. Setting a custom button_label in the field group editor still works exactly as before.

Sub-Field Width Inside a Repeater Is Ignored (All Columns Render as Equal Widths)

Symptoms: In the field group editor a Repeater has sub-fields with explicit Width % values (for example, Year 20% and Awards 80%), but on the post edit screen every sub-field column takes an equal share of the row — two sub-fields land at 50%/50%, four at 25%/25%/25%/25%, etc. The Width % setting appears to save but has no visible effect. Cause (fixed 2026-04-24): The repeater row layout used a flex container with flex: 1 on every cell, overriding whatever wrapper.width the sub-field carried. Top-level fields emitted an inline style from their wrapper width, but the repeater-cell path had no such branch. Fix: Update Field Forge to the latest version. Each repeater sub-field cell now emits a data-width="N" attribute and an inline flex: 0 0 calc(N% - 8px); max-width: calc(N% - 8px) style derived from the sub-field’s wrapper.width, inside a flex row with gap: 8px and flex-wrap: wrap. Widths are honoured for both outer repeaters and nested repeaters/groups/flexes. Cells without a configured width still fall back to flex: 1 and share the row evenly.

Width % Badge in the Editor Does Not Update When You Type

Symptoms: In the field group editor every sub-field has a small rose badge next to its type label (e.g. “Text 20%”) that reflects its wrapper.width. Typing a new value into the Width % input changes the input but leaves the badge unchanged until the page is saved and reloaded — giving the impression that the change is not being saved. Cause (fixed 2026-04-24): The badge was rendered once from the server-side value on initial load. The live input handler updated the JS field state but did not touch the badge element, so the two visuals drifted apart until the next full re-render. Fix: Update Field Forge to the latest version. The wrapper.width input handler now mirrors the current value into the rose badge in real time — adding the badge when a width is first set, updating its text as you type, and removing it when the field is cleared. No functional change, purely a visual consistency improvement.

Translated Page (WPML) Renders the Source-Language Text for Group Fields

Symptoms: After translating a post with WPML, the public front end of the translated language shows the source-language content for fields stored inside a Group — even though the Field Forge metabox in admin clearly shows the correct translation. Typical manifestation: a project detail block renders English labels under a Russian URL (or vice versa). Cause (fixed 2026-04-24): WPML duplicates the source post’s postmeta onto the translation at translation time and does not keep it in sync with later edits. Your edits to the translated post’s Group sub-fields are saved to Field Forge’s own table (wp_fieldforge_values) against the translated post’s ID, but the legacy ACF compatibility layer read Group values only from get_post_meta(), which for the translated post still returned the untouched source-language copy. Fix: Update Field Forge to the latest version. The compatibility layer now prefers values from wp_fieldforge_values when a record exists for the current post, falls back to get_post_meta() only when no record is found, and defensively fills missing sub-fields from ACF postmeta so partially-migrated groups degrade gracefully. No data migration is required — existing translations become correct on the next page load.

Wysiwyg / Image / Text Content Disappears After a Nested `have_rows` Loop

Symptoms: A theme template iterates one repeater or flexible_content field inside another (for example a video or image block nested inside a topside group), and immediately after the inner loop calls the_sub_field('textblock') or the_sub_field('img') on the outer row — the value returns empty, so the surrounding markup appears broken. Images render with src="" and show only the alt text as a fallback; text blocks disappear entirely. Cause (fixed 2026-04-24): When a have_rows() iteration completed, the compat layer unconditionally cleared the current row pointer, even if the iteration was nested inside a still-active outer loop. ACF’s real behavior is that the outer loop’s current row persists until the outer iteration ends. Fix: Update Field Forge to the latest version. On iteration end, the compat layer now restores the current row to the most recent still-active loop on the stack and only clears it when no loops are active. Templates that mix nested have_rows calls — a common ACF pattern — now work as expected.

Repeater “Add Row” Button Not Working

Symptoms: Clicking “Add Row” on a repeater field does nothing, or the button is grayed out. Possible causes and fixes:

Maximum rows reached. If the repeater has a maximum rows setting and you have reached that limit, the Add Row button is disabled. Check the repeater’s configuration for a max rows value.
JavaScript error. Open your browser’s developer console (F12 or Cmd+Option+I) and check for JavaScript errors. A conflict with another plugin or theme script can prevent the repeater from functioning. Common culprits are page builder plugins or admin optimization plugins that concatenate scripts aggressively.
PRO license inactive. Repeater is a PRO field type. If your license expired or was deactivated, repeater functionality may be limited. Check Field Forge > License.
Browser compatibility. Try a different browser or clear your browser cache. Outdated browser versions occasionally have issues with dynamic form elements.

Flexible Content Layouts Missing

Symptoms: When you click “Add Layout” on a Flexible Content field, the dropdown is empty or some layouts are missing. Possible causes and fixes:

Layouts were not defined. Open the field group editor and check the Flexible Content field. Each layout must be explicitly added with a name and sub-fields. If a layout was accidentally deleted, use the Revision History to restore it.
Maximum layout count reached. If a maximum was set for a specific layout type, it will disappear from the dropdown once that limit is reached. Remove an existing instance of that layout to free up the slot.
Conditional logic hiding layouts. If conditional logic is configured on layouts, some may be hidden based on other field values. Check the conditional logic settings.
PRO license issue. Flexible Content requires PRO. Verify your license status.

Performance Issues with Many Field Groups

Symptoms: The admin area feels slow when editing posts, or the field group list takes a long time to load. Possible causes and fixes:

Too many fields on one post. If a single post matches many field groups (resulting in 50+ fields), the editor can become sluggish. Consolidate field groups where possible or use Tab fields to organize large groups into sections. Tabs load fields lazily, improving perceived performance.
Complex conditional logic. Extensive conditional logic with many interconnected rules requires more JavaScript processing. Simplify conditions where possible.
Hosting limitations. Shared hosting with limited CPU and memory can struggle with complex admin pages. Consider upgrading to managed WordPress hosting if admin performance is consistently poor.
Object caching. Install an object caching plugin (like Redis or Memcached) to reduce database queries. Field Forge benefits from object caching because field group definitions are cached after the first load.

Conflict with ACF (Both Active)

Symptoms: Strange behavior, duplicate metaboxes, fields showing values from the wrong plugin, or PHP errors mentioning function redeclaration. Possible causes and fixes:

Deactivate one plugin. Running both ACF and Field Forge simultaneously is only intended during migration. After migration, deactivate ACF. Field Forge provides all the same functions, so your theme code continues working.
Function conflict. If both plugins try to register get_field(), PHP throws a fatal error about duplicate function declarations. Current Field Forge builds defer to ACF whenever ACF is active or being activated through WordPress admin/plugin tooling, so ACF Pro can be activated for migration without hitting a get_field() redeclare fatal. If you still see this error, update Field Forge first, reload Plugins, and activate ACF again.
Options-page fallback during migration. If ACF is active and returns an empty option value while Field Forge has the language-specific option value, Field Forge supplies that value through ACF’s value-loading filter. This narrow bridge keeps LangForge-aware options-page probes consistent during migration; it does not make long-term dual ACF/Field Forge operation the recommended setup.
Double metaboxes. If you see two sets of the same fields on a post, one from ACF and one from Field Forge, it means both plugins have matching field groups and location rules. Deactivate ACF to eliminate the duplicates.

Field Values Lost After Theme Switch

Symptoms: After switching to a new theme, custom field data appears missing on the frontend. Possible causes and fixes:

Theme templates were not updated. Field data is still in the database — it does not disappear when you switch themes. The issue is that the new theme does not contain the template code (get_field(), the_field(), etc.) to display it. Ask your developer to add field output code to the new theme’s templates.
Local JSON path changed. If you were using Local JSON Sync, the JSON files were in the old theme’s folder. Copy the fieldforge-json/ directory from the old theme to the new one, or reconfigure the Local JSON path in Field Forge > Settings.
Field groups are intact. Go to Field Forge > Field Groups to confirm all your field groups still exist. They are stored in the database, not in the theme, so they survive a theme switch.

TypeScript Generation Errors

Symptoms: The TypeScript generation feature produces incorrect types, throws errors, or outputs empty files. Possible causes and fixes:

PRO license required. TypeScript generation is a PRO feature. Verify your license is active.
No field groups defined. TypeScript interfaces are generated from your field group definitions. If you have no field groups, the output will be empty.
Unsupported field types in custom plugins. If you registered custom field types via a plugin, the TypeScript generator may not know how to map them. Check the generated output for any types and add custom type mappings using the fieldforge/typescript/type_map filter.
File write permissions. If the output file cannot be written, check that the target directory has write permissions for the web server.

Import/Export Failures

Symptoms: Importing a JSON file fails, or the exported file is empty or corrupted. Possible causes and fixes:

Invalid JSON format. If you manually edited a JSON export file, a syntax error (missing comma, extra bracket) will cause the import to fail. Use a JSON validator (like jsonlint.com) to check the file before importing.
File too large. Very large exports (hundreds of field groups) may exceed PHP’s upload_max_filesize or post_max_size limits. Increase these values in your PHP configuration, or split the export into smaller files.
Unknown or malformed field definitions. Field Forge rejects imports that contain an unknown field type, malformed sub-fields, malformed Flexible Content layouts, or invalid location rules. Update both sites to the latest Field Forge version and export the JSON again from the source site instead of hand-editing those sections.
Version mismatch. Importing a file exported from a newer version of Field Forge into an older version may fail if the newer version added field types or settings the older version does not recognize. Update Field Forge to the latest version before importing.
Permission issues. The web server needs write access to the uploads directory for temporary file processing during import. Check folder permissions.
Duplicate field keys. If the import contains field keys that already exist in your database, Field Forge shows a conflict notice. Choose to overwrite existing groups or skip duplicates.

—