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, or Products. 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

All ten operators (eq, ne, gt, gte, lt, lte, in, contains, startswith, endswith) are enforced on every filter-accepting tool — whole-catalog semantic_product_search included — with one shared semantics contract. A filter is never silently ignored. The reports that used to read as "operator doesn't work" now come down to operator/attribute mismatches:

Symptom	Likely cause	Fix
A range filter matches nothing	The products don't carry the attribute (a range means it exists and compares — attribute-less rows are excluded, and so is a nonexistent/misspelled attribute key), or the stored values don't read as plain numbers (e.g. "1 200 грн")	Check the exact attribute key and inspect the values with get_category_attribute_values; re-index the feed with a clean numeric field if they're decorated
startswith/endswith misses obvious products	They are case-sensitive and test the whole stored string — comma lists are not split	Use contains (case-insensitive, anywhere) or eq/in for list membership
ne excludes more than expected	ne is the negation of eq — it also excludes case-insensitive list elements	That's the contract; use a different value if you meant exact-string-only
contains matches too much	It matches inside words ("Neath" → Rosneath)	Use eq/in for membership

Partial names use contains

For a partial product name, use a filter such as name contains ASHEN. It matches a case-insensitive literal substring in the top-level product name and works both catalog-wide and within a category. The value must be a nonblank string; * and ? are ordinary characters, not wildcards. For list-shaped fields — native lists such as stickers, or comma-separated attributes such as a coverage list — keep using exact element membership (eq / in) instead: contains matches inside words, so contains "Neath" wrongly matches a list containing Rosneath.

---

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 eq/in/contains 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:

1. 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.
2. 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 eq/in for exact values and list membership, contains for partial text in a string field, and range operators (> / < / …) on attributes whose values read as plain numbers (numeric or text-stored alike) — they're enforced catalog-wide, not just per category, and the bound may be a number or a numeric string.
• 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, check the operator/attribute pairing first (numeric bound on a string-typed attribute? case-sensitive prefix?), then suspect a stale searchable-attribute copy — fix that with a from-scratch re-index (delete & re-add, or ask support).
• A contains filter returns nothing? Confirm the attribute is a string, the value is nonblank, and the fragment appears in that same field. For a product title, use the reserved name attribute; don't use attr_name or add wildcard characters.
• 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.

See also

• Filters, attributes & params
• Getting inventory in
• Search tools reference
• Image search
• Testing search
• Product (commerce) MCP
• How search works