{"record":{"id":"a71861d1db1fd6eb","repo":"medusajs/medusa","slug":"message-a71861","errorCode":null,"errorMessage":"${message}","messagePattern":"\\$\\{message\\}","errorType":"validation","errorClass":"MedusaError","httpStatus":400,"severity":"error","filePath":"packages/modules/providers/search-postgres/src/utils/plan.ts","lineNumber":67,"sourceCode":"   * - `native` — portable Postgres FTS (GIN + `ts_rank`) + `pg_trgm`. Default.\n   * - `lakebase` — Lakebase Search (`lakebase_text` BM25 + `lakebase_vector` ANN).\n   * @default \"native\"\n   */\n  engine?: PostgresSearchEngine\n  /**\n   * Embeds text for `search_options.vector.query`. Required on the lakebase\n   * engine when callers pass a query string instead of a pre-computed `value`.\n   */\n  embedder?: PostgresSearchEmbedder\n  /**\n   * Distance metric for `lakebase_ann` / pgvector indexes.\n   * @default \"cosine\"\n   */\n  vector_distance?: PostgresVectorDistance\n}\n\nfunction fail(message: string): never {\n  throw new MedusaError(MedusaError.Types.NOT_ALLOWED, message)\n}\n\nexport function isSearchable(\n  field: SearchTypes.SearchFieldDefinition\n): boolean {\n  return field.searchable === true || typeof field.searchable === \"object\"\n}\n\nexport function isFacetable(field: SearchTypes.SearchFieldDefinition): boolean {\n  return field.facetable === true || typeof field.facetable === \"object\"\n}\n\nfunction fieldKind(\n  field: SearchTypes.SearchFieldDefinition\n): PostgresFieldKind {\n  switch (field.type) {\n    case \"text\":\n      return \"text\"","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/modules/providers/search-postgres/src/utils/plan.ts#L49-L85","documentation":"Thrown by the search-postgres module's planning utilities (fieldKind, walk, assertQuerySupported, tableNameForIndex) when a query or field definition cannot be planned: an unknown field kind, an unsupported query shape, or an index without a resolvable physical table. The fail() helper raises MedusaError NOT_ALLOWED with a descriptive message.","triggerScenarios":"Querying an index name that has no generated backing table, querying a field whose kind cannot be determined from the index settings, or issuing a query mode (e.g. vector search without a configured embedding) that assertQuerySupported rejects.","commonSituations":"Index settings changed (fields renamed/removed) without re-running index generation, naming mismatch between the index used at query time and the one defined in settings, enabling vector query options without configuring an embedding field/distance, or upgrading search-postgres with breaking plan changes.","solutions":["Verify the index name in the query matches an index defined in your search module index settings","Ensure every queried field is declared in the index settings and regenerate/rebuild the index so the table and plan exist","For vector queries, configure an embedding field and a supported vector_distance option","Re-run the index creation/migration flow for the search-postgres provider after settings changes"],"exampleFix":"// before\nawait searchService.search({ index: \"produtcs\", q: \"shirt\" }) // typo: no table\n// after\nawait searchService.search({ index: \"products\", q: \"shirt\" })","handlingStrategy":"validation","validationCode":"const definedIndexes = await searchModule.indexes() // or from settings\nconst indexNames = new Set(definedIndexes.map((i) => i.name))\nif (!indexNames.has(requestedIndex)) {\n  throw new Error(`Unknown index: ${requestedIndex}`)\n}","typeGuard":"function isKnownIndex(index: string, known: string[]): index is KnownIndexName {\n  return known.includes(index)\n}","tryCatchPattern":"try {\n  await searchModule.search(args)\n} catch (e) {\n  if (e instanceof MedusaError && e.type === MedusaError.Types.NOT_ALLOWED) {\n    // plan-level rejection: verify index settings & rebuild index\n    await searchModule.syncIndex(requestedIndex).catch(() => {})\n  } else throw e\n}","preventionTips":["Keep index names in a typed constant union instead of raw strings","Rebuild/generate indexes after changing index settings","Run a health check on startup that queries each index once"],"tags":["search-postgres","index-plan","unknown-index","medusa-error"],"backgroundTag":"index-not-found","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}