medusajs/medusa · error · MedusaError

${message}

Error message

${message}

What it means

This is the query-planning error channel (query.ts fail()): textRank, clauses, boostWithTypoTolerance, buildHighlightPlan, fields, and buildQueryPlan throw NOT_ALLOWED for search queries the provider can't express — e.g. provider_options under "search-medusa" with unsupported ranking/boost/highlight/typo settings, or query shapes that don't map to the cloud query language.

Source

Thrown at packages/modules/search/src/providers/search-medusa/utils/query.ts:32

import type { MedusaSearchQueryOptions } from "./options"
import { IndexPlan, isSearchable } from "./plan"

export type HighlightPlan = {
  pre_tag: string
  post_tag: string
  fields: { path: string; key: string }[]
}

export type QueryPlan = {
  query: IndexQuery
  skip: number
  take: number
  options: MedusaSearchQueryOptions
  highlight?: HighlightPlan
}

function fail(message: string): never {
  throw new MedusaError(MedusaError.Types.NOT_ALLOWED, message)
}

function providerOptions(
  input: SearchTypes.ProviderSearchQuery
): MedusaSearchQueryOptions {
  return (input.search_options?.provider_options?.["search-medusa"] ??
    {}) as MedusaSearchQueryOptions
}

function textRank(
  input: SearchTypes.ProviderSearchQuery,
  plan: IndexPlan
): RankBy {
  const fields =
    input.search_options?.attributes_to_search_on ?? plan.searchable

  if (!fields.length) {
    fail(

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Check the exact message — it names the rejected option/field combination
2. Restrict provider_options to fields that are searchable in the index definition; remove highlights/boosts on non-searchable fields
3. Scope options under the "search-medusa" key only and remove options belonging to other providers

Example fix

// before
search_options: {
  provider_options: {
    "search-medusa": { highlight: { fields: ["id"] } },
  },
}
// after - highlight only searchable fields
search_options: {
  provider_options: {
    "search-medusa": { highlight: { fields: ["title", "description"] } },
  },
}

function sanitizeProviderOptions(opts, searchableFields) {
  const o = { ...opts }
  if (o.highlight?.fields) {
    o.highlight.fields = o.highlight.fields.filter((f) => searchableFields.includes(f))
  }
  return o
}

const isSearchableField = (f, searchable) => searchable.includes(f)

try { await search(...) } catch (e) { if (e instanceof MedusaError && e.type === "not_allowed" && /boost|highlight|typo|query/i.test(e.message)) { /* strip provider_options and retry plain */ } throw e }

When it happens

Trigger: Passing search_options.provider_options["search-medusa"] with invalid combinations (boost/typo-tolerance settings that conflict with index settings, highlight fields that aren't searchable, unknown ranking modifiers), or query parameters the plan builder cannot translate.

Common situations: Copy-pasting provider_options meant for another provider namespace; boosting non-searchable or non-indexed fields; requesting highlights on keyword-only fields; version drift after provider option keys were tightened.

Related errors

• ${message}
• ${message}
• Deleting Medusa search documents requires filters
• Medusa search accepts at most ${MAX_MULTI_QUERIES} queries p
• A Medusa search document exceeds the ${MAX_WRITE_BYTES}-byte

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/8b35e42301dae07c. Report an issue: GitHub.