Troubleshooting guide

Most surprises come back to one rule: MentionFlow would rather show you an em-dash or an "awaiting" state than a made-up number. Below are the moments that make you ask "why does it say that?". If your question is shorter, the FAQ may answer it directly.

My project shows no data yet

This is almost always timing, not a bug. Sampling runs on a schedule, not on demand. Creating a project does not start a collection right away.

• Your cadence depends on your plan. Trial collects 3 times a week: Monday, Wednesday, and Friday (UTC). Every paid plan collects daily. The daily cycle runs once a day, early morning Europe/Berlin time. A project 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. The Overview header reads "Day N of collection" until the window fills.
• 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 project. First-run banners and empty states match your real cadence, so they tell you when to expect data. If a project that was collecting goes quiet, the Overview Collection strip flags it stale after 36 hours without a run.

An engine I expected isn't showing up

MentionFlow has adapters for ten AI answer engines. Which ones collect for you depends on your plan's engine slots and two deliberate rules.

• You pick your engines from the pickable list, which depends on your plan. Every plan can hold the four defaults (ChatGPT, Perplexity, Gemini, Google AI Overviews) plus Google AI Mode, Copilot, and Grok. Growth and above, including every agency plan, can swap in any of the ten, adding DeepSeek, Mistral, and Claude. Every plan runs four slots. The slot count is workspace-wide and billed once: every project inherits the workspace default set, and a project can customize its own four within the same slots at no extra cost, on Collection.
• Claude is a weekly engine, available on Growth and above. It collects Mondays (UTC) only, because it costs far more per answer and has a small share of consumer search. On any other day you won't see new Claude data.
• Grok is a weekly engine too, available on every plan. It collects Mondays (UTC) only, and there is no way to move it to daily.
• On the Overview, only engines that have actually collected data show a chip. An engine you don't track, or one 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. A knowledge-only engine runs no web search, so it has nothing to cite. See Core concepts.

What to check: your workspace engine selection on Engines, and your plan's slot count in Plans and quotas. If a search-grounded engine is missing, swap it in with the engine picker, which only offers engines your plan can hold.

Two pages show different Share of Voice numbers

This is by design. MentionFlow uses different denominators in a few specific places, and names every one:

• Headline metrics blend only the search-grounded engines: ChatGPT, Perplexity, Gemini, AI Overviews, AI Mode, Claude, Copilot, and Grok. That is a different set from the pickable list above. The blend includes Claude and Grok and leaves out 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 skips the blend and shows that engine on its own. Different denominator, different number.
• A collection config's numbers use the same blended scope as the headline metrics. That covers the monitors CSV export and the Monitor scope chip a legacy multi-config workspace sees. Per-engine views still show every engine collected, knowledge-only ones included, because a per-engine view honestly shows that engine.
• A prompt's detail page uses fixed windows: headline visibility over 7 days, the per-engine sentiment strip over 28 days. The prompt list follows your selected range.

So the "same" metric can legitimately differ between the blended Overview, a single-engine filter, and a prompt detail page. Each is correct for its scope, and the data-honesty page lists every deliberate 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 is always a measured zero. Em-dashes turn up in a few 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 declined to judge them, rather than judging them middling.
• Citation share: until at least one run in the window carried 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 up, but their data vendor's payload carries no product fields yet. That is different from "not sampled", which you can fix, and from a measured 0. See Engine coverage.

The full principle is in How MentionFlow handles missing data.

A delta says "new" instead of a percentage

A period-over-period change is null, shown as "new", when there is no prior window to compare against, or when the previous value was zero. MentionFlow never prints an invented or infinite percentage to fill the cell. Deltas are computed on unrounded inputs, so a rounded display can't create 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. 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 finish, is held out rather than counted as "brand absent".
• Collection is idempotent. There is at most one completed run per prompt, engine, region, and 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, usually a scraper timeout or a rate-limited provider. They fix themselves 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, "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. Blocking a training crawler only opts you out of model training. Blocking a 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-check every row on the server before writing anything.

• Prompts CSV takes up to 500 rows / 2 MB, detects the delimiter for you, 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 matched 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 takes up to 1,000 rows / 5 MB and validates each field. Upserts are idempotent, so re-running corrects rather than duplicates.

What to check: if the import 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 need editor rights.

An invite link isn't working

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

• Already claimed by someone else: it is single-use, 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. Reopen the link and you get the confirmation screen.

If the workspace has hit its seat cap when someone confirms, the join is refused rather than over-filling the plan. 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, so if you lost it, revoke it 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. It is a token bucket, and the REST reads and the MCP endpoint share one bucket per key. The response carries Retry-After and X-RateLimit-* headers. Honor them. Read responses are cached with a one-hour TTL, so polling faster than hourly just returns the same window. Poll at the pace 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 outside 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 fixed demo dataset, not your workspace. MentionFlow serves it when there is no database configured, the database is unreachable, or no brand is visible to your session. A signed-out visitor sees it, and so does a brand-new workspace before onboarding.

Demo surfaces are badged on every page, and demo boards say changes aren't saved. 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 and 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 what the engine said.
• How MentionFlow handles missing data is the single principle behind most "why does it say that?" moments.