medusajs/medusa · critical · MedusaError

Medusa search requires an explicit "environment_handle" prov

Error message

Medusa search requires an explicit "environment_handle" provider option

What it means

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.

Source

Thrown at packages/modules/search/src/providers/search-medusa/utils/client.ts:186

}

export function validateMedusaSearchOptions(
  options: MedusaSearchProviderOptions
): void {
  if (!options?.api_key) {
    throw new MedusaError(
      MedusaError.Types.INVALID_ARGUMENT,
      'Medusa search requires an explicit "api_key" provider option'
    )
  }
  if (!options.endpoint) {
    throw new MedusaError(
      MedusaError.Types.INVALID_ARGUMENT,
      'Medusa search requires an explicit "endpoint" provider option'
    )
  }
  if (!options.environment_handle) {
    throw new MedusaError(
      MedusaError.Types.INVALID_ARGUMENT,
      'Medusa search requires an explicit "environment_handle" provider option'
    )
  }
}

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Add environment_handle to the provider options using the value from the cloud search dashboard
2. Set the corresponding env var in .env and the deployment platform, then restart Medusa
3. Fail fast at boot with a config sanity check so misconfiguration is caught before requests

Example fix

// before
options: { api_key: process.env.SEARCH_API_KEY, endpoint: process.env.SEARCH_ENDPOINT }
// after
options: {
  api_key: process.env.SEARCH_API_KEY,
  endpoint: process.env.SEARCH_ENDPOINT,
  environment_handle: process.env.SEARCH_ENVIRONMENT_HANDLE,
}

if (!process.env.MEDUSA_SEARCH_ENV_HANDLE) {
  throw new Error("MEDUSA_SEARCH_ENV_HANDLE is required for the search-medusa provider")
}

const hasEnvironmentHandle = (opts) =>
  typeof opts?.environment_handle === "string" && opts.environment_handle.length > 0

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Medusa search requires an explicit "api_key" provider option
• Medusa search requires an explicit "endpoint" provider optio
• Module ${moduleConfig.resolve} doesn't have a serviceName. P
• Invalid modules configuration. Should be an array or object.
• Unable to resolve plugin "${pluginPath}". Make sure the plug

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