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 up to about ten minutes before search picks it up — the worker drains the pending-embedding queue on a 10-minute cycle. Wait, then re-search.

If it’s still missing well after that, 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

AI agent retrieval searches the customer’s language first. If you wrote the article in English (your default) and a customer searches in German, it looks for the German translation. The public help center search box works the same way: it resolves the visitor’s language before searching, so both the keyword and the semantic legs read that language’s content, and the results then show the translated title and summary.

There is one narrow exception: if the query contains a configured protected term, or one of that term’s language overrides, KB search can also match the term’s other configured forms in the full-text search path. This helps only for protected terms you’ve configured; it is not general cross-language search for arbitrary words.

• 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 only articles tagged for that role. Untagged articles are hidden.

If your article is tagged admin and your customer is browsing as an end user, they won’t see it. Either tag the article for that role as well, 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 Search Keywords field. Keywords are retrieval-only signals that help search and AI retrieval match synonyms and alternate terms.
• 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:

• Confirm the article exists by calling POST /api/v1/kb/search with {"query": "<your-query>"} if you have an API key with knowledge:read scope. That endpoint is a case-insensitive substring match over title, content, summary and keywords — not the vector retrieval pipeline — so it tells you the article is there, not that retrieval will rank it.
• If the article is published, embedded, available in the right language, visible for the visitor’s role, and still missing from search, contact support with the query, article ID, tenant, language, and market context.

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.