Why is search not finding an article?

You wrote an article, you can see it in the editor, but it doesn’t appear in the public help center search or in AI agent answers. Almost always one of these five reasons:

1. The article isn’t published

Open the article. Check Status in the metadata panel.

• draft — No
• needs-review — No
• published — Yes
• archived — No

Only published articles appear in search and AI retrieval. Set the status to published and try again.

2. The embedding hasn’t finished

Embedding runs as a background job after publish. For a fresh article, expect a delay of a few seconds to a minute or two before search picks it up. Wait, then re-search.

If it’s still missing after a few minutes, the embedding job might have failed. Edit the article (any small edit will do — fix a typo) and save. That re-queues the embedding job.

3. The query language differs from the article language

Atender retrieves articles in the customer’s language first. If you wrote the article in English (your default) and a customer searches in German, retrieval looks for the German translation.

• If translations are still pending — the customer sees the default-language fallback. Wait for translation jobs to finish, or test in your default language.
• If the language isn’t enabled — customers in that language fall back to the default language version.
• If the article was edited but the translation hasn’t re-run — the translation might be out of date with the source. Wait, then re-search.

See Multi-language Knowledge Base.

4. The role filter is hiding it

If your help center has role-based browsing enabled (Role grid block, Role bar block, or /role/<slug> URLs), an article tagged for a specific role only appears for visitors viewing that role.

• Public visitors with no role context see articles tagged for any role plus untagged articles.
• A visitor who’s filtered to a specific role sees articles tagged for that role plus untagged articles.

If your article is tagged admin and your customer is browsing as an end user, they won’t see it. Either un-tag the article or remove the role-filter UI from the public help center.

5. Wrong words in the right places

Search blends keyword matching with semantic vector search. Most queries find what they need either way — but if both fail:

• The query uses different words than the article. Add synonyms to the article’s Keywords field. The keyword path catches these.
• The article body buries the topic. If the question’s answer is in paragraph 7 of a 10-paragraph article, the embedding might not pick it up strongly. Move the answer up; consider splitting the article.
• The title doesn’t match what people search for. A customer searching “cancel my plan” won’t easily find an article titled “Subscription discontinuation procedures”. Use customer language in titles.

When to escalate

If you’ve checked all five and the article still doesn’t appear:

• Check Settings → Knowledge for the search shadow logs (admin-only). If your tenant has shadow logging enabled, recent queries and the articles each path returned are visible.
• Confirm the article appears in /api/v1/kb/articles?q=<your-query> if you have an API key with knowledge:read scope. The API surfaces the same retrieval pipeline.
• Contact support with the article ID and the query that’s missing it.

Common surprises

• Search updates when you publish, edit, or archive. Renaming a category doesn’t trigger a re-embedding. If category-name matching matters, edit each affected article (any small edit) to refresh.
• Archive is forever — well, until you un-archive. Archived articles don’t appear in search. If a customer is asking about a feature you’ve discontinued, the article shouldn’t exist as published; an archived stub is fine for SEO purposes.
• AI retrieval and customer-facing search use the same pipeline. If a customer can’t find it, neither can your AI agents. Fix it once and it’s fixed for both.