Troubleshooting

Common errors grouped by topic, each with symptom, cause, and fix. For issues specific to the embed snippet on your website, see Troubleshooting the embed — that guide covers CORS errors, CSP violations, authorized URL mismatches, and render failures in detail.

Login and authentication

I can’t log in — “Invalid email or password”

Symptom: The login page shows “Invalid email or password.”

Cause: The credentials don’t match any active account, or the email/password combination is wrong.

Fix:

1. Double-check that you’re using the email address you registered with (look for typos or an alias vs. your primary address).
2. Passwords are case-sensitive — make sure Caps Lock is off.
3. If you’re not sure of your password, use the Forgot Password flow on the login page to get a reset link.

💡 Tip: If you registered via an invitation link, your password was set during that registration step, not through any third-party provider.

My session expired mid-task

Symptom: You were working in the dashboard and suddenly see the login screen, or API requests return 401 errors.

Cause: DropAFinder uses JWT tokens with a fixed expiry. When the token expires, your browser session ends and you’re redirected to login.

Fix: Log in again. Your data is safe — nothing is lost when a session expires. After logging in you’ll be returned to /app/dashboard.

💡 Tip: Keeping the dashboard open in a background tab for many hours without activity is the most common trigger for this. There’s no “stay logged in” toggle currently.

I’m on the wrong workspace after logging in

Symptom: The dashboard shows data that belongs to a different workspace than expected.

Cause: The app loads the last active workspace stored in your browser. If you share a machine or recently switched workspaces, the context may not match what you expect.

Fix: Use the workspace switcher (top of the sidebar or the Workspaces page under Settings) to select the correct workspace. If the workspace you need doesn’t appear in the list, you may not have been added as an owner — ask the account holder to add you.

I was invited but the registration link doesn’t work

Symptom: The registration link from your invitation email shows “This registration link is invalid or has expired.”

Cause: Invitation links expire. The backend validates that expires_at > now() at registration time.

Fix: Ask the person who invited you to send a new invitation. Once the new link arrives, complete registration promptly — don’t leave the form open for an extended period before submitting.

Two-factor authentication — “The verification code is invalid” or “This sign-in challenge has expired”

Symptom: After entering your email and password, you’re prompted for a second-factor code (TOTP app, email, or recovery code), and the form shows “The verification code is invalid” or “This sign-in challenge has expired.”

Cause:

• “Verification code is invalid” — the code doesn’t match. For authenticator app codes, this is usually a clock drift issue. For email codes, the wrong code may have been entered.
• “Sign-in challenge has expired” — the two-factor challenge window has a short timeout. If you waited too long to enter the code, the challenge has lapsed and you need to start the login flow again.

Fix:

1. TOTP (authenticator app) code invalid: Make sure your phone’s clock is accurate — TOTP codes are time-sensitive. On iOS, go to Settings → General → Date & Time and ensure “Set Automatically” is on. On Android, go to Settings → General Management → Date and Time.
2. Email code invalid: Check your spam folder. If the email didn’t arrive, start the login flow again to request a fresh code.
3. Challenge expired: Return to the login page and enter your email and password again to start a new challenge.
4. Locked out entirely: If you’ve lost access to your authenticator app and don’t have recovery codes, contact support to have two-factor authentication reset on your account.

💡 Tip: Save your recovery codes when you first set up two-factor authentication. They’re single-use backup codes that let you log in if you can’t access your authenticator app.

CSV import errors

The import button is greyed out or the upload fails immediately

Symptom: The CSV upload is rejected before processing begins, or shows a validation error right away.

Cause: The file must be a .csv or .txt file and cannot exceed 10 MB. Any other format (.xlsx, .xls, .numbers, .tsv) is rejected.

Fix:

1. Export your data as CSV from your spreadsheet application (File → Export → CSV or Save As → CSV).
2. Confirm the file is under 10 MB. If it’s larger, split it into multiple files of up to a few thousand rows each and import them sequentially.

Rows are skipped during import

Symptom: The import completes but the summary shows skipped rows, or fewer locations appear than expected.

Cause: Rows are skipped when:

• The column count in a row doesn’t match the header row.
• The title column is empty or missing — title is the only required column.
• The row contains no non-whitespace values at all (blank row).

Fix:

1. Open the CSV in a plain text editor (not Excel) and look for rows that don’t have the same number of commas as the header row.
2. Make sure every location has a value in the title column.
3. Delete any trailing blank rows at the bottom of the file.

Column names aren’t being recognized

Symptom: Address fields, phone numbers, or other data import as blank even though the file contains the data.

Cause: The CSV importer matches columns by exact header name. The expected column names are:

Fix: Rename your column headers to match the table above exactly (case-sensitive match). The header street address 1 has a space between “street” and “address” — this is the most common mapping error.

The CSV file has encoding problems — strange characters appear in location names

Symptom: Imported location names contain garbled characters like é instead of é, or question marks where accented letters should be.

Cause: The file is not UTF-8 encoded. Many spreadsheet applications default to Latin-1 or Windows-1252 encoding when exporting CSV.

Fix: When exporting from Excel: File → Save As → choose “CSV UTF-8 (comma-delimited)” from the format dropdown. In Google Sheets: File → Download → CSV should export UTF-8 by default. On a Mac you can re-encode an existing file with: iconv -f latin1 -t utf-8 input.csv > output.csv.

The import fails with a message about my plan limit

Symptom: The upload is rejected immediately (before any rows process) with a message like “Your current plan allows up to X locations. Upgrade to import more.”

Cause: Each plan has a location cap (Free: 100, Bronze: 500, Premium: 2,500, Agency Base: 5,000, Agency Growth: 15,000). The system counts how many valid rows are in your file and checks whether importing them would push you over the limit. If it would, the entire import is blocked before it starts.

Fix:

1. Check how many locations you currently have in the dashboard (Locations page).
2. If you’re at or near the limit, either: delete locations you no longer need, or upgrade your plan before importing.
3. If you’re importing a large file in batches, keep each batch small enough to stay within your remaining capacity.

See Billing for a plan comparison and upgrade steps.

The import job gets stuck on “running”

Symptom: The progress bar for a CSV import stalls and never reaches 100%, or the job status never changes from “running.”

Cause: Large files process in a background queue. The queue processes imports sequentially — if other jobs are ahead of yours, it may appear to hang.

Fix: Wait a few minutes and refresh the page. If the job is still stuck after 10 minutes, try the import again with a smaller file. If the problem persists, contact support.

🔴 [NEEDS CLARIFICATION: Is there a per-user or per-workspace queue depth limit that could cause consistent stalling?]

AI location import

The AI import generation times out

Symptom: You submit the AI Import form and the process fails with a message about timing out or an AI generation error.

Cause: The AI generation step calls an external model (Gemini) with up to a 90-second timeout. Complex requests with large geographic scopes or many location types can exceed this. Network issues between the server and the AI provider can also cause timeouts.

Fix:

1. Try narrowing the geographic scope (e.g., “Northeast US” instead of “United States”).
2. Reduce the approximate location count — asking for 50 locations is more reliable than 500.
3. Wait a moment and retry — transient API availability issues usually clear within minutes.

The AI returned wrong or fictional locations

Symptom: The generated draft contains locations that don’t exist, have wrong addresses, or are clearly hallucinated.

Cause: The AI model generates location data based on its training data, not a live business directory. It can invent plausible-looking but incorrect details, especially for obscure or regional businesses.

Fix: This is an expected limitation of AI-generated data, not a bug. The draft review step exists precisely for this reason:

1. Review each location in the draft before approving it. Low-confidence and medium-confidence items are flagged.
2. Edit any incorrect fields directly in the review UI before approving.
3. Reject locations that appear entirely fictional — you can always add them manually later.
4. After importing, use AI Location Improvement to fill in missing fields using real geocoding data.

⚠️ Warning: Always review AI-generated locations before publishing your Finder. Importing without review can result in incorrect addresses appearing on your public map.

Some locations in the draft are marked “low confidence”

Symptom: The review screen shows some items with a low or medium confidence badge.

Cause: Confidence is derived from how complete the location data is and whether there are validation errors. Low confidence means: the name or address information is missing or incomplete, or the location failed validation.

Fix: Click into the item and fill in the missing fields. At minimum, a location needs a name (name) and at least one address or region field before it can be approved. Locations with validation errors can’t be approved until the errors are resolved.

The AI import process shows “no usable draft locations”

Symptom: The generation completes but shows an error like “AI generation returned no usable draft locations.”

Cause: The AI model returned an empty array, or all returned locations failed deduplication or normalization — this can happen if the prompt answers are very sparse.

Fix: Go back and fill in the guided answers more completely, especially:

• Business type
• Geographic scope (be specific — a city or region, not just “worldwide”)
• Customer and location description

AI Location Improvement

The AI improvement process times out or fails

Symptom: You start AI Location Improvement and the process fails with a timeout or AI generation error.

Cause: The improvement job sends your entire workspace location dataset to the AI model (Gemini) with a 90-second timeout. Large workspaces — hundreds of locations with full address and custom field data — can produce prompts that take longer than the limit, or the AI provider may be briefly unavailable.

Fix:

1. Use the location filter in the AI Improvement setup to scope the run to a subset of locations (e.g., only those missing addresses). Smaller datasets complete faster and more reliably.
2. Wait a moment and retry — transient timeouts usually clear within a minute or two.
3. If the failure is consistent for a large workspace, contact support.

AI Improvement returned no suggestions

Symptom: The generation completes but shows an error like “AI improvement returned no usable location suggestions.”

Cause: The AI model reviewed the dataset but either returned an empty response or all returned updates referred to location IDs that don’t exist in the workspace. This can happen when the dataset is very sparse or the workspace has no locations.

Fix:

1. Make sure your workspace has at least a few locations before running AI Improvement.
2. Try enabling “Prioritize missing fields” in the improvement options — this gives the AI a clearer signal about what to fill in.
3. If the workspace has locations but the error persists, retry the run. Transient AI response issues can produce empty outputs.

”No accessible locations matched this AI improvement request”

Symptom: The AI Improvement run fails immediately with “No accessible locations matched this AI improvement request.”

Cause: You ran the improvement with a specific location filter (by ID) and none of the requested IDs belong to the current workspace or are accessible to your account.

Fix: Remove the location filter to run improvement across all workspace locations, or verify that the location IDs you’re passing belong to the correct workspace.

The AI suggested changes that look wrong

Symptom: The improvement draft contains address corrections, phone numbers, or category assignments that appear incorrect.

Cause: Like AI Import, the improvement model suggests changes based on its training data and the patterns it infers from your dataset. It can confidently suggest wrong details, especially for obscure locations.

Fix: This is an expected limitation. The review step exists for this reason:

1. Review each suggestion before approving it. The confidence badge (high / medium / low) indicates how many fields were improved and whether the AI raised any warnings.
2. Edit individual fields directly in the review UI if only part of the suggestion is useful.
3. Reject suggestions for locations where the AI clearly doesn’t have reliable data.

⚠️ Warning: “Apply all” without reviewing individual suggestions can overwrite correct data with AI-inferred guesses. At minimum, scan the low-confidence items before approving.

Geocoding errors

Locations aren’t appearing on the map

Symptom: Locations exist in the system and appear in the list view, but no pins show on the map.

Cause: A location won’t render a map pin if its latitude and longitude are null. This happens when:

• The location was created manually or imported without address data sufficient for geocoding.
• The geocoding call to Google Maps failed (no API key, partial address, ambiguous result).

Fix:

1. Open the location and check whether latitude and longitude are filled in.
2. If they’re empty, add or correct the address fields (street address, city, state, country) and save. The system will attempt to geocode on the next import or AI enrichment pass.
3. For immediate control, you can enter latitude and longitude directly in the location edit form — look up the coordinates in Google Maps, right-click the pin, and copy them.

💡 Tip: The geocoder only sets coordinates when it gets a “rooftop” or “range-interpolated” match — partial matches are intentionally skipped to avoid placing pins at the wrong location.

A location geocoded to the wrong place

Symptom: The map pin appears, but it’s in the wrong city or country.

Cause: Address normalization can fail for short or ambiguous addresses, non-English addresses, or addresses in countries where Google’s geocoding coverage is limited.

Fix: Override the coordinates manually:

1. Open the location in the dashboard.
2. Find the correct coordinates using Google Maps (right-click a point → “What’s here?” shows the lat/lng).
3. Enter the exact latitude and longitude in the location edit form and save.

Manual coordinates are preserved through subsequent AI improvement passes — the geocoder won’t overwrite coordinates that are already set.

Batch geocoding during CSV import partially failed

Symptom: After a CSV import, some locations have coordinates and others don’t, even though all rows had address data.

Cause: Each row’s address is geocoded individually during import. A row is skipped (no coordinates assigned) if:

• The address parts are all empty.
• The geocoding call returned a partial match or an imprecise location type.
• The geocoding API call timed out for that row.

Fix: Locations without coordinates can be geocoded after the fact:

• Use AI Location Improvement with “Prioritize missing fields” turned on — it will attempt to geocode and fill in missing coordinate data for all locations in the workspace.
• Or update each location’s address manually to be more specific, which improves geocoding accuracy.

Embedding issues

The embed-specific troubleshooting guide covers the full range of widget loading, rendering, and script placement issues. Start there for anything related to the finder on your website:

Troubleshooting the embed →

That page covers:

• Widget not rendering at all (missing mount div, missing script tag, wrong script placement)
• Blank render with no console errors (Authorized URLs, unsaved Finder, no Map attached)
• CORS and CSP console errors (what to allowlist)
• Map tiles not loading (tile provider CSP, invalid API key)
• Slow load times (CDN cold cache, large payloads)
• Styling broken (global CSS resets, conflicting CSS variables)

Quick reference for the most common embedding error:

If you see a blank widget with no console errors, the first thing to check is whether your host page’s origin is in the Authorized URLs list. Open Finder Builder → Launch → Authorized URLs and confirm the exact origin (scheme + hostname + port) matches where you’re testing. See Authorized URLs for details.

WCAG and accessibility

My customized theme fails WCAG AA contrast checks

Symptom: After customizing colors in the theme builder, automated accessibility checkers flag contrast failures on text over your chosen background or button colors.

Cause: The theme builder lets you set any hex color, and it doesn’t enforce minimum contrast ratios. Custom color combinations can produce text-to-background contrast ratios below the 4.5:1 AA threshold (3:1 for large text).

Fix:

1. Use a contrast checker such as WebAIM’s Contrast Checker  or the browser’s DevTools accessibility panel.
2. Test your primary color (used for buttons and links) against both white and the widget’s background color.
3. Adjust the lightness or saturation of the failing color until it passes. In most cases, darkening a light brand color by 10–20% is enough.

The places most likely to fail:

• Text on your primary button color (e.g., white text on a light brand color)
• Body text color on your custom background
• Tag label text on tag background colors

🔴 [NEEDS CLARIFICATION: Does the theme builder show any live contrast warnings, or is this entirely manual?]

Keyboard navigation in the widget doesn’t work as expected

Symptom: You can’t navigate the finder widget (search, list, map pins) using only a keyboard, or focus indicators are missing.

Cause: Full keyboard navigation and ARIA landmark compliance for the embedded widget are in progress. Current known limitations:

• Map pin focus via keyboard is not yet supported in all map providers.
• Some interactive elements within location cards may not have visible focus styles in all theme configurations.

Fix: If your site has a legal or contractual WCAG requirement:

1. Contact support to discuss the current accessibility roadmap and timeline.
2. Consider adding a fallback text-based store list alongside the widget for users who rely on keyboard or screen reader navigation.

🔴 [NEEDS CLARIFICATION: Confirm current keyboard nav coverage status — specifically which elements are keyboard-accessible and which aren’t.]

Billing

My payment failed and I’ve lost access to premium features

Symptom: Your subscription status shows “Past due” or “Payment failed,” and features that require a paid plan are no longer accessible.

Cause: Paddle (the payment processor) attempted a renewal charge and the payment was declined. When this happens, the subscription moves to past_due status and the account tier is set back to none.

Fix:

1. Go to Billing in the dashboard.
2. Click Manage billing to open the Paddle billing portal.
3. Update your payment method (card details or PayPal) in the portal.
4. Paddle will retry the failed charge. Once the payment goes through, the billing webhook will update your account automatically.

If your subscription shows “Past due” but you believe your payment method is valid, contact your bank to confirm the charge isn’t being blocked on their end.

💡 Tip: After updating your payment method, allow 2–5 minutes for Paddle’s webhook to reach DropAFinder and refresh your account tier. Then reload the billing page.

I completed checkout but premium features still aren’t available

Symptom: You went through the Paddle checkout, the payment succeeded, but the dashboard still shows the free plan or doesn’t unlock premium features.

Cause: There’s a short delay (usually 5–30 seconds) between Paddle processing the payment and the DropAFinder webhook updating your account tier. The billing page attempts to auto-sync your membership up to 8 times over 16 seconds after a successful checkout.

Fix:

1. Wait about 30 seconds after checkout and refresh the billing page.
2. If that doesn’t work, go to Billing and click Manage billing to open the Paddle portal — if Paddle shows an active subscription there, the sync is just delayed. Reload the billing page again in a minute.
3. If the subscription is active in Paddle but DropAFinder still shows the wrong plan after several minutes, contact support with your account email and the approximate time of purchase.

I can’t access the Manage billing portal

Symptom: Clicking “Manage billing” returns an error like “No active subscription was found for this account” or “Billing management is not available for this subscription yet.”

Cause:

• “No active subscription” — your account has no Paddle subscription ID. This happens if you’ve never completed a checkout, or if the previous subscription was fully canceled.
• “Billing management is not available yet” — your Paddle subscription exists but the management URL isn’t ready. This can happen in the first few seconds after checkout or for some subscription states.

Fix:

• If you’ve never subscribed: go through the checkout flow from the Billing page.
• If you canceled and want to resubscribe: use the Billing page to start a new trial or subscription.
• If the error appeared right after a successful checkout: wait 30–60 seconds and try again — the management URL is generated by Paddle after the subscription is fully activated.

My plan shows a subscription tier I didn’t choose

Symptom: The Billing page shows “Bronze” when you purchased “Premium,” or vice versa.

Cause: Tier assignment is resolved by matching the Paddle price ID in the webhook payload to the configured price IDs for each tier. If the price IDs in the environment configuration don’t match what’s in your Paddle subscription, the tier resolves incorrectly.

Fix: This is a configuration issue on our end, not something you can fix yourself. Contact support with your account email and the tier you expected.

The finder shows old data after I make an edit

Symptom: You saved a change in the Finder Builder, but the public embed still shows the old version.

Cause: The finder payload is cached at the CDN for up to 5 minutes. The pointer file (config.json) has a 60-second CDN TTL; the payload itself is versioned (content-addressable, 1-year TTL). After saving, new visitors get the updated pointer after the 60-second window; existing sessions may continue serving the old payload from browser cache.

Fix: Wait up to 5 minutes. To verify your change without waiting, use the Live Preview in the Finder Builder — it bypasses the CDN and shows your most recently saved state immediately.

See Caching for the full explanation of CDN TTLs.

Workspace switching doesn’t work or takes me back to the wrong workspace

Symptom: You select a different workspace from the switcher, but the data doesn’t change, or you’re redirected back to a previous workspace.

Cause: The workspace switcher updates a context value stored in the browser. If the target workspace is tied to a premium feature and your plan doesn’t include multiple workspaces, the switcher may not allow navigation. Alternatively, browser cache can sometimes hold onto a stale workspace context.

Fix:

1. Confirm your subscription tier supports multiple workspaces (Agency plan required). Free, Bronze, and Premium include one workspace.
2. If you’re on an Agency plan and still having issues, try a hard reload (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows) or open the workspace in an incognito window.
3. Navigate to Settings → Workspaces and click directly into the workspace you want to access from there.

Still stuck?

If none of the above resolved your issue, file a support ticket. Include:

• A clear description of what you expected vs. what happened
• Your account email address
• The workspace name (if applicable)
• Any error messages exactly as shown
• Steps to reproduce the issue

🔴 [NEEDS CLARIFICATION: Support channel — confirm email address, in-app help widget, or another contact method to recommend here.]

For embed-specific issues, also include the finder key and the URL where you’re embedding. See When to file a support ticket in the embed guide for the full list of details that help support reproduce issues quickly.

Where to next

• General FAQ — account, workspace, and feature questions
• Troubleshooting the embed — widget-specific issues
• Billing — plan comparison and subscription management
• Caching — CDN TTLs and cache behavior