{"record":{"id":"f59d936c644044f5","repo":"medusajs/medusa","slug":"medusa-search-requires-an-explicit-api-key-provi","errorCode":null,"errorMessage":"Medusa search requires an explicit \"api_key\" provider option","messagePattern":"Medusa search requires an explicit \"api_key\" provider option","errorType":"validation","errorClass":"MedusaError","httpStatus":400,"severity":"critical","filePath":"packages/modules/search/src/providers/search-medusa/utils/client.ts","lineNumber":174,"sourceCode":"\n  async deleteAll(): Promise<void> {\n    await this.client_.request(\"DELETE\", this.path())\n  }\n\n  query(body: IndexQuery): Promise<IndexQueryResult> {\n    return this.client_.request(\"POST\", this.path(\"/query\"), { body })\n  }\n\n  multiQuery(body: IndexMultiQueryParams): Promise<IndexMultiQueryResponse> {\n    return this.client_.request(\"POST\", this.path(\"/query/multi\"), { body })\n  }\n}\n\nexport function validateMedusaSearchOptions(\n  options: MedusaSearchProviderOptions\n): void {\n  if (!options?.api_key) {\n    throw new MedusaError(\n      MedusaError.Types.INVALID_ARGUMENT,\n      'Medusa search requires an explicit \"api_key\" provider option'\n    )\n  }\n  if (!options.endpoint) {\n    throw new MedusaError(\n      MedusaError.Types.INVALID_ARGUMENT,\n      'Medusa search requires an explicit \"endpoint\" provider option'\n    )\n  }\n  if (!options.environment_handle) {\n    throw new MedusaError(\n      MedusaError.Types.INVALID_ARGUMENT,\n      'Medusa search requires an explicit \"environment_handle\" provider option'\n    )\n  }\n}\n","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/modules/search/src/providers/search-medusa/utils/client.ts#L156-L192","documentation":"The Medusa search provider client validates its options at construction and requires a non-empty api_key. This INVALID_ARGUMENT error is thrown immediately when the provider is instantiated without one, because all requests to the cloud service must be authenticated.","triggerScenarios":"Configuring the search-medusa provider in medusa-config without an api_key entry, or with an empty/undefined value (e.g. a missing MEDUSA_SEARCH_API_KEY environment variable feeding the config).","commonSituations":"Missing MEDUSA_SEARCH_API_KEY in .env (especially in CI/deployments), forgetting to add the api_key key when copying a config example, or supplying process.env.MEDUSA_SEARCH_API_KEY when the variable was never set (undefined).","solutions":["Set api_key in the provider options in medusa-config.ts (e.g. from process.env.MEDUSA_SEARCH_API_KEY)","Add the variable to your .env / deployment environment and restart Medusa","Confirm the key comes from the Medusa cloud search service dashboard and is not empty"],"exampleFix":"// before\nresolve: [\n  {\n    resolve: \"@medusajs/search-medusa\",\n    options: { endpoint: process.env.SEARCH_ENDPOINT, environment_handle: \"...\" },\n  },\n]\n// after\nresolve: [\n  {\n    resolve: \"@medusajs/search-medusa\",\n    options: {\n      api_key: process.env.MEDUSA_SEARCH_API_KEY,\n      endpoint: process.env.SEARCH_ENDPOINT,\n      environment_handle: process.env.SEARCH_ENV_HANDLE,\n    },\n  },\n]\n","handlingStrategy":"validation","validationCode":"if (!process.env.MEDUSA_SEARCH_API_KEY) {\n  throw new Error(\"MEDUSA_SEARCH_API_KEY is required for the search-medusa provider\")\n}","typeGuard":"const hasValidSearchConfig = (opts) =>\n  Boolean(opts?.api_key && opts?.endpoint && opts?.environment_handle)","tryCatchPattern":null,"preventionTips":["Fail fast at boot on missing env vars instead of at first search","Use a startup config schema check (zod) for provider options","Keep an .env.example listing every search env var"],"tags":["search","config","api-key","missing-env-var"],"backgroundTag":"missing-api-key","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}