Gravity Forms 3.1.0.3 fixes a default-country display issue when the gform_countries filter returns an indexed array. The official recommendation is to return an associative array whose keys are country codes and whose values are country names. This is more than a visual default. Add-ons, CRM field maps, tax logic, conditional rules, exports, webhooks, and historical entries may expect either a label or a code. Changing the filter without a contract can fix the dropdown and silently break downstream mappings.
Use this when the Address field loses its default country, locale changes reorder countries, a custom country filter is active, or an integration expects a country name but receives a code.
Quick answer
Update custom gform_countries callbacks to return an associative ISO-code-to-label map. Preserve translated labels for users and define the canonical stored or exported value for integrations. Test new and existing entries across site locales, default settings, dynamic population, conditional logic, payment and CRM feeds, exports, notifications, and webhooks. Do not remap historical data blindly just because the current dropdown now uses codes.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| English locale | US default | US key and United States label |
| Translated locale | Same country | Stable key and translated label |
| CRM feed | New submission | Mapped provider value |
| Historical entry | Stored country name | Readable without silent rewrite |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Inventory country filters and consumers | Locate every gform_countries callback, Address field default, locale override, dynamic population source, field map, export transform, webhook, and reporting rule. | The configured default country appears in every supported locale. |
| Define the canonical code and display label | Record whether each destination expects ISO alpha-2 code, full country name, translated label, or a provider-specific value. | New entries store and export the documented canonical representation. |
| Return associative ISO-code keys | Change the filter fixture to associative country-code keys and verify default selection in every supported site and user locale. | CRM, payment, tax, webhook, and analytics mappings remain correct. |
| Retest locales and downstream feeds | Submit new entries and inspect entry detail, notification, merge tag, export, API, payment, tax, CRM, and analytics values. | Historical entries still render and report without an uncontrolled bulk rewrite. |
What to check first
- Locate every gform_countries callback, Address field default, locale override, dynamic population source, field map, export transform, webhook, and reporting rule.
- Record whether each destination expects ISO alpha-2 code, full country name, translated label, or a provider-specific value.
- Change the filter fixture to associative country-code keys and verify default selection in every supported site and user locale.
- Submit new entries and inspect entry detail, notification, merge tag, export, API, payment, tax, CRM, and analytics values.
- Compare historical entries and build an explicit compatibility transform where a downstream system still expects names rather than codes.
Field notes
- Write the expected result before changing anything and keep one repeatable canary fixture for the full test window.
- Record exact versions and UTC timestamps because cache purges, retries, scheduled actions, and deployments can change the evidence between tests.
- Test the public browser path and the server-side result, not only an admin preview or isolated API response.
- Close the task only after the visible workflow, stored record, logs, and relevant downstream system agree.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
add_filter( 'gform_countries', function( $countries ) {
return [
'US' => 'United States',
'CA' => 'Canada',
'GB' => 'United Kingdom',
];
} );
Why this usually happens
- An indexed array has no stable country-code key for matching the configured default.
- Locale changes alter labels or order while integrations rely on the visible name.
- A field map confuses display labels with canonical stored values.
- Historical entries use a previous representation that a new strict mapping no longer recognizes.
Decision rule
Use country codes as stable keys and translated names as presentation. Every downstream consumer must document which representation it receives instead of inferring it from the visible dropdown.
Production verification checklist
- The configured default country appears in every supported locale.
- New entries store and export the documented canonical representation.
- CRM, payment, tax, webhook, and analytics mappings remain correct.
- Historical entries still render and report without an uncontrolled bulk rewrite.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Inventory country filters and consumers
- Define the canonical code and display label
- Return associative ISO-code keys
- Retest locales and downstream feeds
- Add explicit historical compatibility where needed
Mistakes to avoid
- Changing production code, cache settings, form fields, webhook endpoints, or firewall rules before preserving the exact failure, current versions, and rollback point.
- Treating one successful page load or dashboard status as proof while browser behavior, PHP logs, scheduled jobs, delivery records, and downstream data remain unchecked.
- Testing a different role, device, locale, form, URL, order state, cache state, or plugin combination than the workflow that users actually reach.
- Leaving helper plugins, debug logging, copied secrets, broad exclusions, temporary endpoints, or test notifications active after the verification window.
Questions teams ask during testing
Can I run this directly on production?
Begin with read-only checks and preserve evidence. Use staging for changes that affect PHP, cache generation, form submission, payment, email, or customer state. When production is necessary, use one named canary, a short monitored window, and a tested rollback.
How do I avoid a false positive?
Match the exact plugin and WordPress versions, URL, role, device, locale, cache state, and integration path. Repeat the same fixture before and after the change, then compare stored evidence rather than relying on memory.
What evidence should I keep?
Keep UTC time, versions, affected URL or record ID, expected result, actual result, relevant log lines, configuration snapshot, change made, rollback point, and final verification. Remove credentials, payment details, and personal data.
When should I bring in a specialist?
Escalate when the site is unavailable, checkout or lead capture is affected, a security boundary is unclear, several systems disagree, or the next step could destroy evidence. A concise incident packet makes outside help much faster.
What to tell the client or owner
Give the owner a short evidence packet with the affected workflow, exact versions, UTC test time, fixture ID, expected and actual result, key logs, the change made, rollback point, final result, owner, and next review date. Redact credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP migrate the Gravity Forms country mapping safely.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references