{"record":{"id":"3bde1458c11a8eb2","repo":"medusajs/medusa","slug":"medusa-search-requires-an-explicit-environment-ha","errorCode":null,"errorMessage":"Medusa search requires an explicit \"environment_handle\" provider option","messagePattern":"Medusa search requires an explicit \"environment_handle\" provider option","errorType":"validation","errorClass":"MedusaError","httpStatus":400,"severity":"critical","filePath":"packages/modules/search/src/providers/search-medusa/utils/client.ts","lineNumber":186,"sourceCode":"}\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":168,"sourceCodeEnd":192,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/modules/search/src/providers/search-medusa/utils/client.ts#L168-L192","documentation":"Beyond api_key and endpoint, the provider requires an environment_handle — the identifier of the search environment/cluster to operate on. This INVALID_ARGUMENT error is thrown at construction when it is missing.","triggerScenarios":"Configuring the search-medusa provider without environment_handle in options, or referencing an env var (e.g. process.env.SEARCH_ENV_HANDLE) that is not defined in the runtime environment.","commonSituations":"New integrations set up api_key/endpoint but skip the handle from the cloud dashboard; environment variable missing in a deployed environment; the key was renamed between local and production configs.","solutions":["Add environment_handle to the provider options using the value from the cloud search dashboard","Set the corresponding env var in .env and the deployment platform, then restart Medusa","Fail fast at boot with a config sanity check so misconfiguration is caught before requests"],"exampleFix":"// before\noptions: { api_key: process.env.SEARCH_API_KEY, endpoint: process.env.SEARCH_ENDPOINT }\n// after\noptions: {\n  api_key: process.env.SEARCH_API_KEY,\n  endpoint: process.env.SEARCH_ENDPOINT,\n  environment_handle: process.env.SEARCH_ENVIRONMENT_HANDLE,\n}\n","handlingStrategy":"validation","validationCode":"if (!process.env.MEDUSA_SEARCH_ENV_HANDLE) {\n  throw new Error(\"MEDUSA_SEARCH_ENV_HANDLE is required for the search-medusa provider\")\n}","typeGuard":"const hasEnvironmentHandle = (opts) =>\n  typeof opts?.environment_handle === \"string\" && opts.environment_handle.length > 0","tryCatchPattern":null,"preventionTips":["Copy api_key, endpoint AND environment_handle together from the cloud dashboard","Fail fast at boot on missing env vars","Add a single validateSearchEnv() helper run in the config entrypoint"],"tags":["search","config","environment-handle","missing-env-var"],"backgroundTag":"missing-provider-config","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}