Troubleshooting guide

Most surprises in MentionFlow trace back to a deliberate honesty rule — the product would rather show you an em-dash or an "awaiting" state than a fabricated number. This guide covers the moments that most often prompt a "why does it say that?", with the real reason and what to do. If your question is shorter, the FAQ may answer it directly.

My monitor shows no data yet

This is almost always timing, not a bug. Sampling runs on a schedule, not on demand — creating a monitor does not trigger an immediate collection.

• Your cadence depends on your plan. Trial and Starter collect 3×/week — Monday, Wednesday, and Friday (UTC); Growth, Agency, and Scale collect daily. The daily cycle runs once a day (early morning, Europe/Berlin time), so a monitor created just after today's cycle waits for the next one.
• Until the first run lands you see an honest "awaiting first run" state rather than zeros, and the Overview header reads "Day N of collection" until the window fills — so a partial window is never presented as a low score.
• A metric built from fewer than five runs carries a low-confidence badge. Early day-to-day movement is expected noise; judge trends, not ticks.

What to check: that today is a collection day for your plan, and that at least one full cycle has run since you created the monitor. First-run banners and empty states are written to match your actual cadence, so they'll tell you when to expect data. If a monitor that was collecting goes quiet, its card is flagged stale after 36 hours without a run — see Monitors.

An engine I expected isn't showing up

MentionFlow has adapters for ten AI answer engines, but which ones actually collect for you is governed by your plan's engine slots and a couple of deliberate rules:

• You choose your engines from the pickable list — ChatGPT, Perplexity, Gemini, Google AI Overviews, Google AI Mode, Copilot, DeepSeek, and Mistral — up to your plan's slot count (four on Trial/Starter/Growth/Agency; the whole list on Scale). Reusing an engine across another monitor costs no extra slot.
• Claude is not a selectable slot: it runs weekly (Mondays, UTC) on the Scale plan only, because it costs far more per answer and has a small consumer-search share. On any other day or plan, you won't see Claude data.
• Grok is not selectable yet — it ships later as a paid add-on.
• On the Overview, only engines that have actually collected data show a chip — an engine you don't track (or that hasn't returned a run yet) never appears as an empty option.
• DeepSeek and Mistral answer from model knowledge only, so their citations are honestly empty. That's not a bug — a knowledge-only engine runs no web search, so it has nothing to cite. See Core concepts.

What to check: your monitor's engine selection and your plan's slot count in Plans and quotas. If you want a search-grounded engine you're missing, add it in the monitor engine picker — the picker mirrors your usage exactly, so it can only offer slots you actually have.

Two pages show different Share of Voice numbers

This is by design, and knowing the rule saves a support ticket. MentionFlow uses different denominators in a few specific places, and it names every one of them:

• Headline metrics blend only the search-grounded engines — ChatGPT, Perplexity, Gemini, AI Overviews, AI Mode, Claude, Copilot, and Grok. This is a different set from the pickable list above: the blend includes Claude and Grok and excludes the knowledge-only DeepSeek and Mistral, so a knowledge-only engine can't distort the number. The Overview and Competitors Share of Voice — and the API — all use this same blended scope, so the dashboard and the API never disagree.
• Filtering to a single engine bypasses blending and shows that engine honestly, on its own — a different denominator, a different number.
• A monitor card's visibility includes every engine that monitor collected, knowledge-only ones included, because it's describing that monitor, not the blended headline.
• A prompt's detail page uses fixed windows — headline visibility over 7 days, the per-engine sentiment strip over 28 days — while the prompt list follows your selected range.

So the "same" metric can legitimately differ between the blended Overview, a single-engine filter, a monitor card, and a prompt detail page. Each is correct for its scope. The data-honesty page lists every deliberate denominator difference. If a competitor's mentions look undercounted, check whether engines call them by a name you haven't aliased in Matching rules.

A metric shows an em-dash (—) instead of a number

An em-dash is never a zero — it means "not enough to say yet". A 0 in MentionFlow is always a measured zero. You'll see an em-dash in intentional places:

• Sentiment — until at least one scored brand mention exists. If a run's language-model pass failed, its mentions are "unscored", not neutral — the system declining to judge, not judging it middling.
• Citation share — until at least one run in the window carried any citations.
• Average position — until your brand has appeared at least once.
• Estimated impressions / demand — when a prompt has no measurable demand signal.
• Clicks — until your tracking snippet fires its first-ever event (a 0 would falsely claim tracking is live).
• Shopping "awaiting vendor data" — Perplexity and Gemini shopping are wired but their data vendor's payload carries no product fields yet; that's distinct from "not sampled" (fixable by you) and from a measured 0. See Engine coverage.

Full principle in How MentionFlow handles missing data.

A delta says "new" instead of a percentage

A period-over-period change is null — rendered "new" — when there's no prior window to compare against, or when the previous value was zero. MentionFlow never prints a fabricated or infinite percentage to fill the cell, and deltas are computed on unrounded inputs so a rounded display can't invent a change. Once a real prior window exists, the delta appears.

I see failed or queued runs

Runs have three states — queued, completed, and failed — and only completed runs feed metrics:

• In the Answers feed, incomplete runs (queued or failed) appear in a separate strip and never enter your metrics. A failed collection or a run whose extraction couldn't complete is held out rather than counted as "brand absent", which would corrupt the numbers.
• Collection is idempotent: there is at most one completed run per prompt × engine × region × UTC day, so a retry after a failure overwrites nothing and duplicates nothing.

What to do: a few failed runs in a cycle are normal (a scraper timeout, a rate-limited provider) and self-correct on the next cycle. If an engine fails every cycle, check that engine's coverage above.

A crawler's robots.txt verdict says "Couldn't check"

On a crawler agent page, the robots.txt verdict is honest about its own certainty. "Couldn't check" means MentionFlow couldn't fetch your robots.txt at all — a DNS failure, a timeout, or a 5xx. The verdict is unknown, not a green light: your site may well be blocking the agent. MentionFlow retries on the next view. The other verdicts — Allowed, Blocked, and Not addressed — mean what they say; a training crawler blocked only opts you out of model training, while a blocked search-index or live-fetch crawler removes you from the answers that agent feeds.

A CSV import was rejected

Both importers preview first and re-validate every row on the server before writing anything:

• Prompts CSV accepts up to 500 rows / 2 MB, auto-detects the delimiter, and is all-or-nothing against your pooled prompt quota — if the whole batch won't fit, nothing is written. The preview shows ready / duplicate / invalid counts before you confirm. Duplicates are detected on normalized text (trim + collapse-whitespace + lowercase) against your active and paused prompts; archived prompts are re-importable. Topics are resolve-only — an import matches an existing topic but never creates one.
• Shopping CSV accepts up to 1,000 rows / 5 MB with per-field validation, and upserts are idempotent, so re-running corrects rather than duplicates.

What to check: if the import says it would exceed your quota, archive prompts to free pooled slots (pausing doesn't free a slot) — see Plans and quotas. If specific rows are invalid, the preview names them. Imports are blocked in demo mode and require editor rights.

An invite link isn't working

Invites are single-use and expire after seven days, and joining takes an explicit confirmation — merely opening a link never enrolls anyone. A dead link tells you honestly why:

• Already claimed by someone else — a single-use link, and someone else confirmed it first.
• Already used by you — you've already joined; the page links you to your dashboard.
• Expired or Revoked — past seven days, or cancelled from the members list.
• Addressed to a different email — the invite named another address. That records who it was meant for; it doesn't restrict who can use the link. Joining links your signed-in account.
• Signed out — you're asked to sign in or create an account first, then see the confirmation screen on reopening the link.

If the workspace has hit its seat cap when someone confirms, the join is refused rather than over-filling the plan, and the link stays valid until a seat frees. Full model in Workspace and members.

The API returns 401 or 429

• 401 Unauthorized — a missing or invalid key. Send your workspace key as a bearer token: Authorization: Bearer mf_.... There is no X-API-Key header and no query-string key. Keys are shown in plaintext once at creation; if you lost it, revoke and create a new one. A 403 instead means you used an ingest-scoped key on a read endpoint — reads need a full key. See Authentication.
• 429 Rate limit exceeded — reads are metered per key at 120 requests per minute (a token bucket; the REST reads and the MCP endpoint share one bucket per key). The response carries Retry-After and X-RateLimit-* headers; honor them. Because read responses are cached with a one-hour TTL, polling faster than hourly just returns the same window — poll on the order of your data cadence and the limit is unreachable.
• 503 means the API is disabled for that deployment; 404 "Unknown brand" means the brand id is out of your key's scope (the API never confirms whether another workspace's id is real). Full shapes in Errors and Limits.

Everything says "Demo data" or "Preview — sample data"

You're seeing the deterministic demo dataset, not your workspace. MentionFlow serves demo data when there's no database configured, the database is unreachable, or no brand is visible to your session — for example a signed-out visitor, or a brand-new workspace before onboarding. Demo surfaces are badged on every page, demo boards state that changes aren't saved, and editing actions like import and bulk are hidden. Some features (live shopping, agent analytics, prompt import) run on live workspaces only and show labelled sample data in the demo. Sign in to a workspace that owns at least one brand to see your real data. The demo/live split is described in the architecture overview.

Still stuck?

• The FAQ covers shorter questions.
• Every metric traces to a receipt — open the answer behind a surprising number and read exactly what the engine said.
• How MentionFlow handles missing data is the single principle behind most "why does it say that?" moments.