Documentation

Troubleshooting Gravity Search

Last modified: June 23, 2026

Introduction

This guide covers common issues that can happen when configuring Gravity Search and explains which settings to check first.

Most issues are caused by one of four areas: the Search Form is not connected to a Target Form, field mappings are incomplete, location data has not been indexed, or the wrong shortcode/layout setup is being used.

Gravity Search Setup Tab

Before You Begin

Before troubleshooting a specific issue, verify the following:

  • The Search Form is connected to the correct Target Form.
  • The Target Form contains entries.
  • Search Settings have been saved.
  • The Search Form ID is being used in any shortcodes.

No Results Displayed

If the search page loads but no entries are returned, check the following:

  • Confirm that the Search Form is connected to the correct Target Form.
  • Confirm that the Target Form contains active entries.
  • Check the Search Form field mappings.
  • Review Search Defaults and Predefined Filters for rules that may be excluding entries.
  • Test with fewer filters or broader filter values.
  • If Initial Load is disabled, submit the Search Form before expecting results.

If the Search Form is disabled, results may still load from defaults and predefined filters, but visitors will not see filter controls. If the search uses proximity filtering, also verify that entry locations have been indexed and imported correctly.

Filters Are Not Working

When a Search Form field does not affect results, the most common cause is a missing or incorrect field mapping.

  • Open the Search Form settings.
  • Go to the Search Form tab.
  • Confirm that each Search Form field is mapped to the correct Target Form field.
  • Confirm that the selected operator matches the expected behavior.
  • Check whether Filter Match Mode should be Match All Rules or Match Any Rule.
Gravity Search Filter Mapping Settings

Location Source Fields Are Missing

If no fields appear under Location Source Fields or Location Data Scope, Gravity Search has not detected any geocoded location sources on the Target Form.

  • Confirm that Entry Geocoding is enabled on the Target Form.
  • Confirm that one or more fields are selected under Fields to Geocode.
  • Save the Target Form settings after making changes.
  • Refresh the Search Form settings page.
  • Verify that the selected fields are supported location source fields.

Location Source Fields become available only after geocoding has been configured on the Target Form.

See Understanding Location Data & Proximity Search for more information about how location sources are created and indexed.

Proximity Search Is Not Working

Proximity Search requires both indexed entry locations and correctly configured Search Form proximity settings.

  • Make sure Entry Geocoding is enabled on the Target Form.
  • Make sure at least one supported field is selected under Fields to Geocode.
  • Run the Import Existing Entry Locations tool for existing entries.
  • Select the indexed location fields under Location Data Scope / Location Source Fields.
  • Enable Proximity Search on the Search Form.
  • Select the Address Field, Radius Field, and Units Field if your search uses them.
  • Test with a wider radius to confirm that entries are not being excluded by distance.

If existing entries are not appearing in proximity searches, see Importing Existing Entry Locations.

Gravity Search Location Scope Picker

Map Is Not Showing

If the map container does not appear, check the Map Settings and shortcode placement.

  • Confirm that Map display is enabled in the Map Settings tab.
  • Confirm that Location Source Fields are selected.
  • If using separate component shortcodes, confirm that [gfgeo_search_map id="123"] is placed on the page.
  • Confirm that the shortcode ID belongs to the Search Form, not the Target Form.
  • Check that the Google Maps API key is configured and that required Google Maps services are enabled.
  • Open your browser console and check for Google Maps API errors.

Markers Are Not Showing

If the map appears but no markers are displayed, the map is loading but no indexed location data is available for the current result set.

  • Confirm that matching entries have valid indexed locations.
  • Run the Entry Locations Importer for existing entries.
  • Make sure the selected Location Source Fields match the fields that were indexed.
  • Check whether current filters or predefined filters are excluding the expected entries.
  • Try a search with no filters or a wider proximity radius.

If existing entries were created before Entry Geocoding was enabled, run the Import Existing Entry Locations tool.

Details Page Is Not Working

If details links do not work or the Details Page is empty, review the Details View settings.

  • Confirm that a Details Page is selected.
  • Confirm that the Details Page is published and publicly accessible.
  • Confirm that the Details Page contains the required details shortcode when using Structured Fields mode.
  • Use [gfgeo_search_entry_details] on the selected Details Page.
  • Confirm that result items are configured to link to the Details Page if links should appear.
  • Test with an entry that exists and belongs to the connected Target Form.

Shortcodes Are Not Working

Gravity Search shortcodes must use the Search Form ID.

  • Use [gfgeo_search id="123"] for the complete search output.
  • Use [gfgeo_search_form id="123"] for the form only.
  • Use [gfgeo_search_results id="123"] for results only.
  • Use [gfgeo_search_map id="123"] for map only.
  • Confirm that 123 is the Search Form ID, not the Target Form ID.
  • Confirm that the Search Form is active and properly configured.

If separate component shortcodes are used, all components on the page should use the same Search Form ID.

Useful Checklist

  • Search Form is connected to the correct Target Form.
  • Target Form has active entries.
  • Google API services are enabled when using maps, autocomplete, or geocoding.
  • Search Form fields are mapped to Target Form fields.
  • Initial Load setting matches the expected behavior.
  • Predefined filters are not unintentionally excluding entries.
  • Entry Geocoding is enabled when using proximity or maps.
  • Existing entry locations have been imported.
  • Shortcodes use the Search Form ID.
menu-circle