Top 10 search and KQL traps
SharePoint Search often answers HTTP 200 even when the query, the property or the index is wrong, so failures hide as empty or oversized results. These ten traps cost the most time for anyone building search, reports or RAG on top of it.
- Search REST API needs odata-version 3.0The one header behind mysterious search 500s from SPFx; set it once and a whole class of errors disappears.The header behind mysterious search 500s
- Search ignores unknown managed properties — silentlyA misspelled property name answers 200 with an empty or Null result instead of an error; only sortlist tells you it does not exist.A made-up property name returns HTTP 200 with full results; auto-created Choice properties are not queryable; probe with a fake name, map to RefinableString
- "Search finds nothing here" is usually a site missing from the index — not a permissions problemConfirm the site is indexed with three queries before you debug a query or permissions that were never wrong.Three queries tell you whether the site is in the index at all, before you debug a query that was never wrong
- An unparenthesized OR in your KQL query silently escapes the scope filterAND binds tighter than OR, so an unparenthesised OR escapes your scope filter; parentheses alone are not enough either.KQL AND binds tighter than OR; wrapping the query in parens is necessary but NOT sufficient (text can break out of them), and an empty custom path list must not fall back to the whole tenant
- Two KQL restrictions on the same property separated by a space are OR-ed — a range needs ANDTwo restrictions on the same property are joined with OR, so a size or date range matches everything; write ranges explicitly.KQL joins restrictions on the SAME managed property with OR when only a space separates them, so a size or date range written as two restrictions matches every item; write ranges with explicit AND or a..b
- A library with NoCrawl returns nothing from Search — and silently blinds anything built on SearchA library excluded from search returns 0 with no error, so search based AI never sees it; check NoCrawl first.Excluded containers return 0 with HTTP 200 and no log, so Search-backed AI never sees them; provisioning that excludes data lists must not inherit that onto content libraries; reindex can't be forced over REST…
- Duplicate trimming hides exactly the file copies you are searching forSearch collapses identical files by default, so a duplicate finder reports none exactly when perfect copies exist.Search collapses identical content by default, so a copy-finder returns "no copies" exactly when perfect copies exist; trimduplicates=false on duplicate-hunting queries only
- Graph Search returns 0 hits — you passed the user's question as the queryStringPassing a user's question as queryString returns 0 hits; turn it into keywords and treat what's new as a listing.Translate question→keywords; "what's new" is a listing (* + default date sort, custom sort = 400); per-entity KQL only as documented
- SharePoint Search finds nothing for a question in an inflected language — add prefix-wildcard stems, and never turn zero hits into "latest documents"KQL matches exact word forms with implicit AND, so inflected languages miss; add stem* variants and relax before giving up.KQL is implicit AND and matches exact word forms, so Czech inflected forms miss; add a stem* variant in code, relax before giving up, and never serve a date-sorted inventory as sources for a specific question
- Scope SharePoint Search to hundreds or thousands of sites with RefinementFilters — and or() with one value returns nothingTo limit search to a list of sites use postquery RefinementFilters; or() with one value returns zero rows, use equals().To restrict any Search query to an explicit list of site collections, POST to /_api/search/postquery with RefinementFilters SPSiteUrl:or(...) (tested with 3,000 URLs); a single value must use equals() because or() with…