Dealer Locator Troubleshooting: Fix Common Issues
Looking for Dealer Locator? View the full Dealer Locator page to explore features, configuration options, and pricing.
Something not working as expected with the Dealer Locator? This page collects the problems we see most, from a dealer page that gives a "page not found" to dealers missing from the map, a Google key that's rejected, or an import that stops looking up coordinates. Start with the quick checks to narrow things down, then go to the matching issue for the cause and the fix. At the end you'll find how to switch on debug logging and what the log files tell you. Most issues come down to a setting, an address or an API key, and can be solved from the admin without a developer.
Common issues and solutions for the Dealer Locator.
Quick Diagnostics
- Check that Enabled is Yes under Stores → Configuration → Magmodules → Dealer Locator → General, for the store view you're testing.
- Flush the cache under System → Cache Management.
- Click Run Self-test in the Branding section of the configuration: it checks the map provider, the API keys, a test address lookup and the number of dealers.
- Check the dealer grid for On Map: No and Active: No.
- Check the logs:
var/log/dealer-locator-error.logand, with debug mode on,var/log/dealer-locator-debug.log.
Common Issues
Issue: The dealer page shows "page not found"
Symptoms:
https://example.com/dealersgives Magento's 404 page
Solution:
- Check Enabled for this store view (General section).
- Check the URL Key under Page & SEO for this store view. The page is only on that address, e.g.
service/dealersinstead ofdealers. - Check Marketing → URL Rewrites for a rewrite on the same address: URL rewrites are handled before the dealer page and win. (A CMS page with the same address is no problem: the dealer page comes first.)
- Flush the cache.
Prevention:
- After changing the URL key, update your menu and footer links.
Issue: A dealer is missing on the storefront
Symptoms:
- The dealer is in the admin grid, but not in the list or on the map
Solution:
- Check Active is Yes.
- Check On Map. With "No", the dealer has no coordinates and can't be shown. Open the dealer, check the address and save, or use Find Location in the grid.
- Check Store View: the dealer must be assigned to the store view the visitor is on, or to All Store Views.
- Is a category filter selected on the page? Choose "All product categories".
Prevention:
- Filter the grid on On Map: No after every import.
Issue: "The address ... was not found"
Symptoms:
- Warning after saving or importing a dealer
- With Google Maps: "was not found exactly; the closest match is ..."
Solution:
- Check the spelling of street, postcode and city, and that the country is right.
- Put the house number in the street field:
Domplein 9. - Leave out extras such as "Unit 4" or "Industrial estate", which the map services often don't know.
- Still not found? Enter latitude and longitude by hand. You can find them in any map service: right-click the location and copy the two numbers.
Prevention:
- Keep addresses in the format a letter would be sent to: street and number, postcode, city.
Issue: The map doesn't load ("The map could not be loaded")
Symptoms:
- The list works, but where the map should be, you see "The map could not be loaded. The list of dealers still works."
Solution:
- With Google Maps: click Test API key below the Google Maps Browser API Key (Map & Geocoding). It shows per API whether the key works, and Google's reason if it doesn't. Alternatively, in your browser's developer console you'll see Google's reason, such as
RefererNotAllowedMapError(the key isn't allowed for this domain) orApiNotActivatedMapError(the Maps JavaScript API isn't enabled in Google Cloud). - Check that billing is enabled for the Google Cloud project.
- With a Content Security Policy in "restrict" mode on the storefront: the module adds the domains it needs, but a custom policy might block them. Check the console for "Content-Security-Policy" errors.
Prevention:
- Run the self-test after changing keys.
Issue: The map shows a "Show map" notice instead of the map
Symptoms:
- A text about loading the map, with a Show map button
Solution: This is the cookie consent setting doing its job: Load Map Only After Cookie Consent is on, and the visitor hasn't given consent yet.
- Accept cookies in the cookie notice, or click Show map, to see the map.
- Using a consent tool other than Magento's cookie notice or Hyvä's banner? Let it send the
dealer-locator:consent-grantedevent when the visitor accepts (see the best practices guide). - Don't need consent for the map? Switch the setting off.
Issue: Coordinates aren't looked up with Google Maps
Symptoms:
- Saving a dealer gives "The address could not be geocoded: Google Geocoding returned REQUEST_DENIED: ..."
- The self-test fails on "Check if the geocoding provider responds"
Solution:
- Click Test API key below the Google Geocoding Server API Key (Map & Geocoding), or read Google's message after "REQUEST_DENIED"; it says what's wrong.
- Check the Google Geocoding Server API Key. It must be allowed for your server's IP address, not restricted to your domain (HTTP referrers): a domain-restricted key only works in the browser.
- Check that the Geocoding API is enabled in the Google Cloud project, and billing is active.
Prevention:
- Use separate keys for the browser and the server.
Issue: The import stopped looking up coordinates
Symptoms:
- The report says "Looking up coordinates was stopped after 60 seconds"
- Many dealers have On Map: No after a large import
Solution:
- This is expected with OpenStreetMap and large files: it allows one lookup per second, and the admin stops after 60 seconds so the page doesn't time out.
- Filter the grid on On Map: No, select the dealers and use Find Location. Repeat until all are done.
- Or, on the server:
bin/magento dealerlocator:geocode, which has no time limit.
Prevention:
- Use
bin/magento dealerlocator:importfor the first large import.
Issue: Import rows fail
Symptoms:
- The report lists errors per row
Solution: Common messages and their fix:
- Required columns are missing: ... - the first row must contain the column names, at least
code,nameandcountry. - Country "..." is not a known two-letter country code - use codes like
NL,BE,DE, not country names. - Code "..." is also used in row ... - every dealer can only be in the file once.
- Unknown store views: ... - use the store view codes from Stores → All Stores, or
all. - Unknown product categories: ... - create them first, or switch on Create product categories that don't exist yet.
- Dealer code "..." may only contain letters, digits, "-", "_" and "." - remove spaces and other characters from the code.
Prevention:
- Run new files with Validate only, don't save anything first.
Issue: A visitor's search finds a place in another country
Symptoms:
- Searching a postcode shows dealers sorted from a place far away
Solution:
- Set Restrict Address Search to Countries to the countries you sell in.
- Check that your dealers have the right country: when the setting is empty, the search is limited to the countries of your dealers.
Issue: Changes don't show on the storefront
Symptoms:
- A saved dealer or setting isn't visible on the page
Solution:
- Dealer and category changes refresh the page automatically. Configuration changes need a cache flush under System → Cache Management.
- With Varnish or another full page cache in front of Magento, flush that cache as well.
- Reload the page without the browser cache (Ctrl+F5 / Cmd+Shift+R).
Debug Mode
Navigate to: Stores → Configuration → Magmodules → Dealer Locator → Debug & Logging
- Set Debug Mode to Yes to log extra details to
var/log/dealer-locator-debug.log, such as addresses that weren't found. - Errors are always logged to
var/log/dealer-locator-error.log, for example a rejected API key or a map service that couldn't be reached. - The buttons in this section show the last lines of both logs, so you don't need server access.
Example error log line:
[2026-11-10T14:38:01] MagmodulesDealerLocatorError.ERROR: Geocoding D-1003: Google Geocoding returned REQUEST_DENIED: The provided API key is invalid.
Switch debug mode off again when you're done; the log isn't needed for normal use.
Need More Help?
Documentation:
- All Help Articles - Complete documentation overview
Support:
- Contact Support - Get help from our team
For a complete overview of features and configuration options, see Dealer Locator.