These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content
EmbeddingTroubleshooting the embed

Troubleshooting the embed

Symptoms, causes, fixes. Read top-to-bottom on a first integration; jump to a specific section when something specific breaks. Each section starts with the symptom you’d see and works back to the cause.

Diagnostic checklist (do this first)

Before searching for an exotic cause, walk through this 90-second checklist:

  1. Is the mount div in the page HTML? View page source (not dev tools “Elements” tab — those reflect post-render state). You should see literal <div id="finder-app" finder-key="…"> in the source.
  2. Is the script tag present and correct? Same view-source check; look for <script type="module" src="https://cdn.locationfinders.com/snippet.js">.
  3. Is the host page’s origin in Authorized URLs? Open the Finder Builder → Launch → Authorized URLs and verify the exact origin (scheme + host + port).
  4. Is the browser console clean? Open dev tools, reload the page, look at the Console tab for red errors mentioning finder, cdn.locationfinders.com, api.locationfinders.com, or CSP violations.

90% of integration issues are caught by these four checks. If you’ve done them and something is still off, find your symptom below.

Nothing renders at all

Symptom: The page loads, but the area where the widget should be is empty (no map, no list, no search bar).

Most likely causes, in order:

  1. The mount div is missing. The widget can’t render without <div id="finder-app" finder-key="…"> somewhere in the page. View source and confirm it’s actually there.
  2. The finder-key attribute is missing. The mount div exists but doesn’t have a finder-key= attribute. The widget doesn’t know which Finder to load.
  3. The script tag is missing or malformed. Without type="module" the script silently fails to parse in modern browsers. Without the correct src URL, nothing fetches.
  4. The script tag runs before the mount div exists. If the script is in <head> and the div is in <body>, ordering may matter depending on whether you used defer or type="module" (which defers by default). Easiest fix: put the script tag just before </body>.
  5. A JavaScript error elsewhere on the page is preventing the widget from initializing. Check the console.

Full snippet reference: Script tag.

Renders blank but no console errors

Symptom: The mount div is in the page, the script is loading (you see the network request succeed in dev tools), there are no console errors — but the widget area is empty.

Most likely causes:

  1. Origin isn’t on the Authorized URLs list. This is the single most common cause for this symptom. Verify the host page’s exact origin against your Finder’s Authorized URLs list. See Authorized URLs.
  2. The Finder hasn’t been saved. A brand-new Finder that hasn’t been saved yet has no published payload. Open it in the dashboard and save.
  3. The Finder has no Map attached. A Finder with no Map has no Locations to render. Add a Map under the Finder Builder’s Setup section.
  4. CDN cache is still cold. If you just made changes, wait ~5 minutes and retry. See Caching.

Renders but the styling looks wrong

Symptom: The widget appears, but it’s visually broken — overlapping text, missing borders, fonts wrong, etc.

Most likely causes:

  1. Aggressive global CSS reset on the host page. Rules like * { all: unset } or * { margin: 0; padding: 0; box-sizing: border-box } applied globally can affect the widget’s rendering. Scope your resets to your site’s content area, not the whole page.
  2. Conflicting CSS variables on :root. The widget reads CSS variables to apply your theme colors. If your host page sets the same variable names on :root for unrelated purposes, you may see color leakage. The widget’s variables are namespaced; the practical impact is rare but possible.
  3. Custom font not loading. If you’ve configured a font in Typography that the host page hasn’t loaded, the browser falls back to a system font and the layout may shift slightly. The widget loads its own fonts in production, but locally-served font files on a strict CSP can be blocked.

🔴 [NEEDS CLARIFICATION: Confirm exactly how the widget handles font delivery on host pages — does it load fonts from its own CDN, or rely on system fonts? The answer affects this section.]

Map tiles fail to load

Symptom: The widget renders the search bar and list, but the map area is grey, blank, or showing a tile-loading placeholder.

Most likely causes:

  1. Content Security Policy is blocking tile fetches. If your host page enforces a CSP, you need to allowlist the map provider’s tile domain in connect-src and img-src. The exact domain depends on your provider:
    • TomTom: *.tomtom.com
    • Mapbox: *.mapbox.com, events.mapbox.com
    • HERE: *.here.com
    • OpenStreetMap: *.openstreetmap.org, *.tile.openstreetmap.org
  2. Map provider API key is missing or invalid. If you’re using bring-your-own-key for a map provider and the key is expired or wrong, the provider returns 401 on tile requests.
  3. Provider is rate-limiting. High-traffic finders on free-tier provider keys can hit rate limits. Either upgrade your provider plan or pick a different provider in Map style.

Locations don’t appear

Symptom: The widget loads, the map renders, but no Locations are listed and no markers show.

Most likely causes:

  1. No Map is attached to the Finder. Open the Finder Builder → Setup → and confirm a Map is selected.
  2. The attached Map has no Locations. Open the Map and confirm Locations are attached to it.
  3. Refinements have a default applied that filters everything out. If you’ve configured a refinement to apply on load (e.g., “country = Canada”) and your test data has no matching Locations, the result is empty.
  4. Locations fail to geocode. A Location without a latitude/longitude won’t render on the map (and may not appear in the list, depending on layout). Open Locations and look for entries with empty coordinates.

Console error: CORS

Symptom: Browser console shows Access to fetch at 'https://api.locationfinders.com/...' from origin 'https://...' has been blocked by CORS policy.

Most likely cause: This is rare for normal embeds — DropAFinder’s API permits all origins by default. If you’re seeing CORS errors, the most likely explanation is:

  1. You’re behind a corporate proxy that strips Origin headers. Some enterprise proxies break CORS in surprising ways. Test on a different network.
  2. A browser extension is interfering. Disable extensions and retry.
  3. You’re hitting a different origin than expected. Confirm the request URL in the console error matches cdn.locationfinders.com or api.locationfinders.com, not some intermediary.

Console error: CSP violation

Symptom: Browser console shows Refused to connect to '...' because it violates the following Content Security Policy directive: ....

Cause: Your host page has a Content Security Policy that doesn’t allow the widget’s required fetches.

Fix: Add the widget’s origins to your CSP:

  • script-src — https://cdn.locationfinders.com
  • connect-src — https://cdn.locationfinders.com, https://api.locationfinders.com, plus your map provider’s domains (see “Map tiles fail to load” above)
  • img-src — your map provider’s tile domain, plus https://cdn.locationfinders.com (for any uploaded location images)
  • style-src — usually fine without changes; the widget injects its own styles inline

Console error: mixed content

Symptom: Browser console shows Mixed Content: The page at 'https://example.com/...' was loaded over HTTPS, but requested an insecure resource 'http://...'.

Cause: Something on the page is requesting an http:// resource from an https:// page. The widget itself only fetches over HTTPS, so the most likely cause is:

  1. A Location’s image_url was set to an http:// URL. Find the Location and re-upload the image (the upload returns an https:// URL).
  2. A custom field value contains an http:// link rendered as an image somewhere. Update the value.

The widget loads, but is slow

Symptom: The widget eventually renders but takes more than ~3 seconds on a typical connection.

Most likely causes:

  1. First-load CDN cache miss. On the very first visitor to your finder after a recent edit, the pointer fetch may go to the CDN’s origin rather than the edge. Subsequent visitors are faster.
  2. Large finder payload. Finders with thousands of Locations have larger payloads. If your finder doesn’t actually need every Location loaded up-front, configure a default refinement (e.g., “within 50 km of the visitor”) that narrows the initial set.
  3. Slow host network conditions. The widget makes several fetches; on slow connections this compounds. There’s no widget-side fix beyond payload-size reduction.

I changed something and the widget still shows old data

Symptom: You saved a change in the Finder Builder, but visitors (or you, in an incognito window) still see the old version.

Cause: CDN cache. The pointer file is cached for 5 minutes; once it expires, the next load picks up your latest version.

Fix: Wait 5 minutes. If you need to verify your change without waiting, the dashboard’s Live Preview shows your unsaved/just-saved state immediately (it bypasses the CDN by design — see Preview mode).

See Caching for the full explanation.

When to file a support ticket

If you’ve tried the relevant section above and it’s still broken, file a ticket. Include:

  • The finder key (the one in your finder-key= attribute)
  • The host URL where you’re trying to embed (the URL bar contents — even staging URLs are useful)
  • The browser and version you’re testing in
  • A screenshot of the browser console with the page reloaded (so the relevant errors are at the top)
  • A description of what you expected to see vs. what you actually see

That’s enough information for support to reproduce most issues without back-and-forth.

🔴 [NEEDS CLARIFICATION: Support channels — email address, in-app form, public Slack/Discord, or none. Confirm what to recommend here.]

Where to next

Script tag (canonical embed method)Autocomplete providers