Appearance
Search troubleshooting & best practices
The failure modes that actually bite in production — why the agent returns the wrong item, an empty result, or a spinning feed — and the exact fix for each. Use the cheat sheet to jump straight to the cause; the sections below have the fixes, framed as what you click in the app and how you phrase the search your agent runs.
Where product search lives in the app
Your catalog is a product source under Knowledge Base (https://app.mychatbot.app/knowledge-base) — an XML Product Feed, Product Feed, Product Spreadsheet, Products, or a store connector (WordPress / OpenCart). Each source has a Refresh control that re-processes it and shows import progress. The search itself is exposed to your agent (and to external tools) through the Product (commerce) MCP — see Product (commerce) MCP.
Cheat sheet
| Symptom | Likely cause | Fix |
|---|---|---|
| Filters silently return nothing (or error) on an older catalog | The source was indexed before the current searchable-attribute format existed | Re-index from scratch: in Knowledge Base, delete & re-add the source, or ask support to run a full re-index. |
| Same query flips its top result / lands in a different category run-to-run | Generic product names dominate ranking, so ties break arbitrarily | You can fix this: filter by category/vendor first, and prefer descriptive (semantic) queries. If it persists, ask support to tune relevance for your catalog. |
| Duplicate results, "deleted" items reappear, catalog looks doubled | An old source was deleted/recreated and left a stale copy in the search index | Ask support to wipe the stale index, or delete & re-add the source cleanly. |
Filtering by vendorcode / sku / model returns nothing | SKU-like codes aren't part of the general attribute filter | Search the code directly (or look the product up by id); exact-code search auto-switches to exact matching. Ask support to make SKU filterable. |
| Import status stuck, the source spins forever | The import stalled mid-job | Click Refresh to re-check; then re-import the source. |
| Image search surfaces the wrong look-alike above the text answer | A near-duplicate image was mis-pinned to the top | Have the agent show the top image to confirm; add a text disambiguator; ask support to tighten image matching. |
| Prices/attributes mangled, everything lands in one generic category | The feed's format was auto-detected incorrectly | Re-add the source using the matching source type, or ask support. |
| Searches time out on a huge catalog | Too many categories searched at once | Search within one category, or split a very large catalog across multiple sources. |
| An attribute is visible on the product but can't be filtered | The field was kept as raw detail and never extracted into a filterable attribute | Check what's filterable (see Attribute extraction blind spots); re-index with the correct source type or ask support. |
Which filter operators work where
Two independent filter mechanisms back the search tools. This distinction explains most "my filter returns nothing" reports.
| Filter type | When it's used | Operators | Scope |
|---|---|---|---|
| General attribute filter (primary) | The default path for every search | is / in only | All non-code attributes, catalog-wide |
| Category-scoped filter (fallback) | Auto-triggered only when the general filter returns empty/errors and filters are present | Full set: is, is not, >, >=, <, <=, in, starts with, ends with | Leaf categories only |
TIP
Need a range filter (> / < / >= / <=) — e.g. price under 1000 — target a leaf category (search within one category id). Range operators only exist on the category-scoped filter, which is per-leaf-category.
Empty filters on an older catalog
Symptom: a source that was created a while ago returns nothing for every filtered search, or filters throw, while an unfiltered search still returns products.
Why: filters run against a searchable attribute blob that older catalogs were indexed before it existed — so there's nothing for is/in filters to match against.
Auto-heal: when filters are present, search retries once against category-scoped attributes as a safety net. It's a band-aid, not a repair, and it only fires when filters are present — so unfiltered queries are never affected.
Permanent fix — a from-scratch re-index. This rewrites the searchable attributes for every product. It isn't a self-serve toggle; there are two ways to trigger it:
- Delete and re-add the source in Knowledge Base. A fresh source indexes from scratch with the current pipeline. (Its id changes, so re-point any agent search tools or MCP URLs that reference it.)
- Contact MyChatBot support on Telegram with your account id and source id, and support runs the re-index server-side.
In the app
Knowledge Base → open the product source → Refresh re-processes it, but only a full re-index (delete & re-add, or support) rebuilds the searchable attributes. https://app.mychatbot.app/knowledge-base
Very old catalogs
The oldest catalogs use a simpler, typed-column-only filter path and don't get the general attribute filter at all. If a legacy source needs the modern filtering, MyChatBot has to opt it in — ask support.
Name pollution / rank instability
Symptom: the same query returns a different rank-1 product (or picks a different category) on repeated runs; generic products crowd out the specific match.
Why: short, generic product names carry a lot of weight in ranking. When many products share near-identical names, that signal dominates and ties break arbitrarily — so the top result is brittle run-to-run.
Fix it from the query (do this first). These are the levers you control, and they fix the symptom directly:
- Filter first. Narrow by category or vendor before ranking — the surest stabiliser. (For example, filter
vendor is OksanaMukha, then search.) - Prefer semantic intent. For descriptive queries (
"linen summer dress"), phrase the query so meaning leads rather than leaning on exact-name matching.
If it still misbehaves — ask support to tune relevance. Whether MyChatBot should lean more on names or more on meaning depends on the kind of query your agent mostly issues:
- Generic-term queries (
"dress","running shoes") where many products share near-identical names — the name signal is noise, and meaning should lead. This is the fix for the instability above. - Exact product-name / model queries (
"OksanaMukha Camilla", a precise model string) where the name is the answer — you want the exact name match to win.
MyChatBot tunes search relevance per catalog; tell support your dominant query type and they'll adjust it for you.
It's not a one-way rule
A strong reliance on names is what causes instability for generic queries, but it's exactly what makes exact-name queries land on the right item. There's no single setting that helps both — which is why support tunes it to your query mix. From the request side, filtering category/vendor first is your fix either way.
TIP
When a category is genuinely ambiguous, category selection already prioritises categories whose top products contain all your query terms before frequency-ranked ones. Adding a concrete filter turns that heuristic into a hard guarantee.
Duplicate sources & stale index copies
Symptom: deleted products still appear, results are duplicated, or a catalog looks like two overlapping inventories.
Why: deleting and recreating a source, or pointing a new source at the same feed, can leave an old copy behind in the search index that search still reads.
Fix: the stale copy has to be wiped (both from the search index and from MyChatBot's records) before re-ingesting. This is a support operation.
- Contact support with your account id and the source id(s) you expect, and they'll remove the stale copy and re-ingest cleanly.
- Self-serve equivalent: delete the source in Knowledge Base and re-add it once. Avoid pointing two live sources at the same feed.
WARNING
Wiping a source's index is irreversible — it removes the main, per-category, and image data for that source. Support confirms which source before deleting.
SKU / product-code filtering blind spot
Symptom: filtering by vendorcode, sku, productcode, or model returns nothing, even though the value is clearly on the product.
Why: SKU-like codes are deliberately excluded from the general attribute filter, so a filter on them can't see them. They're still fully searchable — just as exact codes, not as filter values.
Fixes:
- Exact-code queries already work. When a query looks like a SKU/barcode, the search automatically switches to exact matching (and skips reranking), so it finds the code even though you can't filter on it.
- Look it up directly when the SKU is the product id — a by-id lookup is the fastest and most reliable path for "does this exact code exist".
- Make it filterable with a from-scratch re-index (delete & re-add the source, or ask support). Then filter within a leaf category.
TIP
For a "does this exact code exist" question, prefer a by-id lookup or a plain code query over building a filter — it's faster and doesn't depend on the code being indexed as a filterable attribute.
Import stuck ("processing" forever)
Symptom: a product source sits on a processing/importing state and the progress bar spins indefinitely.
Why: the import stalled mid-job, so the interim status was never advanced.
How the app self-heals: re-checking the status projects a long-stuck import to failed (read-only — it doesn't corrupt anything), and a background cleanup tidies up crashed jobs afterward.
Fix: click Refresh on the source to re-check status, then re-import it to retry.
In the app
Knowledge Base → the stuck source → Refresh. If it reliably dies at the same point on a large catalog, re-import and watch the counts climb — a stall at a fixed count usually points at one bad record or an oversized image set, not a flaky importer. https://app.mychatbot.app/knowledge-base
Image pin misfire
Symptom: an image search surfaces a visually similar but wrong product at the top, overriding the item the text query already disambiguated.
Why: the "these two images are near-identical" step can occasionally over-fire on images that only look similar, and that near-duplicate then displaces the correct text-driven answer.
Guard already in place: a near-duplicate is only allowed to jump to the top when it's a very close visual match and clearly closer than the runner-up. There's still a residual failure mode when two genuinely different products share a layout or silhouette.
Fixes:
- Have the agent display the top image so the shopper confirms it before the agent commits to "this is the one".
- Add a text disambiguator — name, colour, collection — alongside the image.
- Ask support to tighten image-match strictness, or fall back to the more conservative visual-match path, for your catalog.
In the app
Image search only exists for sources where Index images was turned on when you connected them. If image search returns nothing, re-open the source and enable it, then Refresh.
WARNING
Image matching alone can't always separate two different products that share a layout. When identity matters, combine the image with a text disambiguator rather than relying on visual similarity to break the tie.
Wrong feed format detected
Symptom: prices/attributes come out mangled, or every product lands in one generic category.
Why: MyChatBot auto-detects your feed's format. A permissive fallback can occasionally grab a specialised feed that a stricter reader should have handled.
Fix: re-add the source using the matching source type in Knowledge Base (XML Product Feed, Product Feed, a store connector, etc.), or ask support — changing the format on an already-indexed catalog is a from-scratch re-parse, which isn't self-serve.
TIP
The detected format is reflected in the source's details. If an import produced a huge number of products all filed under one generic category, that's the classic signature of a fallback reader having swallowed the feed — re-add with the right source type and re-import.
Large-catalog performance
Symptom: searches on a large catalog get slow or time out; results feel thin because each category returns very few items.
Why: a broad search can fan out across many category groups in parallel. As the number of categories grows, each one returns fewer items — both slow and low-recall.
Fixes:
- Search within one category instead of a broad search — a category-scoped search (scoped to a single category id) queries just that one group and sidesteps the fan-out entirely.
- Filter to fewer categories in the query so fewer groups are searched.
- Split very large catalogs across multiple sources so no single one is huge.
- If you need the fan-out itself bounded for your catalog, ask support.
TIP
Product searches run over MCP have roughly a 60-second ceiling. If you consistently know the category, always prefer the category-scoped search over a broad one.
Attribute extraction blind spots
Symptom: an attribute is clearly visible when you fetch a product's details, but you can't filter on it.
Why: vendor and price fields are nested differently in every feed format. Anything the importer doesn't map to a known attribute is kept as raw product detail — visible when you look at the product, but not turned into a filterable attribute.
Fix:
- Introspect what's actually filterable for the category — the agent can:
- list which attribute names exist.
- check the type and common values for one attribute.
- pull the live filter values with their counts.
- If the attribute you need isn't there, it has to be re-extracted with a from-scratch re-index using the correct source type (delete & re-add, or ask support), so the field becomes a filterable attribute instead of raw detail.
WARNING
Raw product detail is intentionally a pass-through. Never assume a value you see there is filterable — always confirm against the category's filterable attributes and available filter values before building agent logic around a filter.
Best practices
Do
- Filter category or vendor before relying on ranking for anything ambiguous.
- Use
is/inon the default path; reach for a leaf category when you need range operators (>/</ …). - Repair a legacy source (or apply an attribute change) with a from-scratch re-index — delete & re-add the source, or ask support.
- Introspect filterability — check the category's filterable attributes and available filter values — before wiring filters into agent prompts.
- For exact codes/SKUs, look products up by id or run a plain code query.
Don't
- Don't build filters against values you only saw in raw product detail.
- Don't delete-and-recreate a source without letting the old copy be wiped — you'll leave a stale index behind (ask support if in doubt).
- Don't lean on image matching alone to distinguish two look-alike products — add a text disambiguator.
- Don't leave a mis-detected feed on the wrong source type — re-add with the matching one.
Test it
- Filters return nothing? Run the same search without filters. If products come back, it's a searchable-attribute or operator-scope issue — fix it with a from-scratch re-index (delete & re-add, or ask support), or move the range filter into a leaf category.
- Rank looks unstable? Run the query 3× and compare the top result. If it flips, add a category/vendor filter and re-test.
- Suspect a duplicate/stale index? Compare the product sources you see in Knowledge Base against the ones you expect; if a "deleted" catalog still shows up, ask support to wipe the stale copy.
- Regression-guard your fixes. Add a query → expected-product-ids case to your known-hits suite so the fix can't silently regress. See Testing search.