Documentation

Troubleshooting Gravity Search

Last modified: August 6, 2026

Introduction

This guide covers common Gravity Search issues and the settings you should check first.

Most problems are related to the Target Form connection, field mapping, Initial Load behavior, indexed location
data, map configuration, Details Routing, Details Display, or an incorrect Search ID in a shortcode.

Search Setup tab in Gravity Search Settings

Before You Begin

Before troubleshooting a specific feature, confirm that:

  • The Search is connected to the correct Target Form.
  • The Target Form contains active entries.
  • The Search Settings have been saved.
  • Any component shortcodes use the Search ID, not the Target Form ID.
  • The page containing the Search has been updated and caches have been cleared.

No Results Are Displayed

If the Search loads but no entries appear, check the following:

  • Confirm that the correct Target Form is selected under Search Setup.
  • Confirm that the Target Form contains active entries.
  • Review Defaults & Filters for predefined rules that may exclude entries.
  • Temporarily remove filters or use broader values to identify an overly restrictive rule.
  • Check the Field Mapping Rules under the Search Form tab.
  • Confirm that the selected operators are appropriate for the Target Form fields.
  • If proximity filtering is active, verify that the entries have indexed locations.

Check Initial Load

Open the Initial Load tab and review Load results on initial page load.

When this setting is disabled, results do not appear until the visitor submits the frontend search form. If the
Search Form is disabled and you want results to appear automatically, enable Load results on initial page load.

A Search can operate without a visible search form by using Search Defaults, predefined filters, and Initial Load
settings.

Search Form Filters Are Not Working

When a visitor-facing search field does not affect the results, the most common cause is an incomplete or incorrect
mapping rule.

  1. Open the Search and select the Search Form tab.
  2. Locate Field Mapping Rules.
  3. Confirm that the search-form source field is mapped to the correct Target Form field.
  4. Confirm that the selected comparison operator matches the expected behavior.
  5. Review Filter Match Mode.

Use Match All Rules (AND) when every populated mapping must match. Use Match Any Rule
(OR) when an entry can match any one of the populated rules.

Also confirm that the visitor entered a value. Empty frontend fields generally do not create query rules.

Gravity Search Field Mapping Rules

Location Source Fields Are Missing

If no fields appear under Location Data Scope, Gravity Search has not detected an eligible location
source on the Target Form.

  • Open the Target Form settings.
  • Enable Enable Entry Geocoding.
  • Select at least one supported field under Fields to Geocode.
  • Save the Target Form settings.
  • Return to the Search and refresh Search Setup.

Supported fields include Gravity Geolocation Geocoder fields, Gravity Forms Address fields, Single Line Text fields,
and Paragraph Text fields selected for entry geocoding.

After the fields become available, select the sources the Search should use under Location Data
Scope.

Proximity Search Is Not Working

Proximity Search requires a search origin and indexed coordinates for the Target Form entries.

  • Enable Entry Geocoding on the Target Form.
  • Select the correct Fields to Geocode and save the settings.
  • Run Import Existing Entry Locations for entries created before geocoding was configured.
  • Select the indexed fields under Search Setup → Location Data Scope.
  • Open the Search Form tab and enable Enable Proximity Search.
  • Select the appropriate Address Field.
  • Select the Radius Field and Units Field when those visitor controls are used.
  • Check the Default Radius and Default Units under Defaults & Filters.
  • Test with a larger radius to confirm that entries are not simply outside the selected distance.

If you do not use a visible search form, configure a default proximity origin, radius, and units as required by your
Search.

Gravity Search Location Data Scope

The Map Is Not Showing

Open the Map tab and check Map Display Mode.

  • Display in Results: The map appears as part of the complete Search output.
  • Display via Shortcode: Add [gfgeo_search_map id="123"] where the map should
    appear.
  • Disable: The map is not rendered.

Also confirm that:

  • At least one field is selected under Search Setup → Location Data Scope.
  • The shortcode contains the correct Search ID.
  • The Google Maps API key is configured.
  • The required Google Maps APIs are enabled for the key.
  • Billing and API restrictions are configured correctly.
  • The page does not contain a visible JavaScript or Google Maps API error.

Map Markers Are Not Showing

If the map appears but contains no result markers, the map is loading but the current result set does not provide
usable indexed locations.

  • Confirm that matching Target Form entries contain valid indexed coordinates.
  • Run Import Existing Entry Locations for older entries.
  • Confirm that Location Data Scope contains the same fields that were indexed.
  • Check that result markers are enabled under Map → Result Markers.
  • Review Defaults & Filters for rules that exclude the expected entries.
  • Test without frontend filters or with a larger proximity radius.
  • Confirm that results are loading; no matching results also means there are no result markers.

The Details Page Is Not Working

If details links are missing, return a 404 error, lead to the wrong page, or display no entry content, review both
Search Setup → Details Routing and Details Display.

  • Confirm that a published Details Page is selected under Details Routing.
  • Confirm that the entry belongs to the Search’s Target Form.
  • Confirm that the details URL contains a valid Entry ID.
  • Enable the result title link or details link if links should appear in search results.
  • Enable the appropriate details link if links should appear in map info windows.
  • Confirm that the intended Output Mode is selected under Details Display.

The Details URL Returns a 404 Error

  • Confirm that the selected Details Page exists and is published.
  • Confirm that URL Mode is set to the intended value.
  • When using Pretty mode, confirm that the URL Structure and Search URL Slug are correct.
  • Confirm that the Entry ID at the end of the URL is present and valid.
  • After changing WordPress permalinks, open Settings → Permalinks and save the settings to
    refresh rewrite rules.
  • Review the Example URL under Details Routing and compare it with the URL being tested.

Structured Fields or Custom HTML

When using Structured Fields or Custom HTML, place the following shortcode on the
selected Details Page:

[gfgeo_search_entry]

Place the shortcode where the individual entry output should appear.

Page Content

When using Page Content, build the entry layout directly in the selected WordPress page using
supported Gravity Forms merge tags. The shortcode is not required in this mode.

If merge tags appear as plain text, confirm that Page Content is the selected Output Mode and that the page was
opened through a valid details URL.

Shortcodes Are Not Working

The primary Gravity Search component shortcodes use the Search ID:

  • [gfgeo_search id="123"] displays the complete Search.
  • [gfgeo_search_form id="123"] displays only the optional frontend search form.
  • [gfgeo_search_results id="123"] displays only the results.
  • [gfgeo_search_map id="123"] displays only the map.

Confirm that 123 is the Search ID, not the Target Form ID.

If separate component shortcodes are used, they must all use the same Search ID. The form-only shortcode outputs
nothing when Disable Search Form is enabled.

When using the map shortcode, set Map Display Mode to Display via Shortcode.

The [gfgeo_search_entry] shortcode is used differently. When placed on the selected Details Page, it
uses the Search and entry information from the current details URL to render the requested entry.

Troubleshooting Checklist

  • The Search is connected to the correct Target Form.
  • The Target Form contains active entries.
  • Search Settings have been saved.
  • Search-form fields are mapped to the correct Target Form fields.
  • Initial Load matches the intended workflow.
  • Defaults and predefined filters are not unintentionally excluding entries.
  • Entry Geocoding is enabled when using location features.
  • Fields to Geocode have been selected and saved.
  • Existing entry locations have been imported.
  • Location Data Scope contains the correct indexed fields.
  • Map Display Mode matches the page layout.
  • The Details Page, URL Mode, URL Structure, and Search URL Slug are configured correctly under Details Routing.
  • The appropriate Output Mode is configured under Details Display.
  • The [gfgeo_search_entry] shortcode is present when using Structured Fields or Custom HTML.
  • Shortcodes use the Search ID.
  • Google Maps APIs, billing, and key restrictions are configured correctly.
  • Website and page caches have been cleared after changing settings.
menu-circle