medusajs/medusa · critical · MedusaError

Medusa search requires an explicit "api_key" provider option

Error message

Medusa search requires an explicit "api_key" provider option

What it means

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.

Source

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

  async deleteAll(): Promise<void> {
    await this.client_.request("DELETE", this.path())
  }

  query(body: IndexQuery): Promise<IndexQueryResult> {
    return this.client_.request("POST", this.path("/query"), { body })
  }

  multiQuery(body: IndexMultiQueryParams): Promise<IndexMultiQueryResponse> {
    return this.client_.request("POST", this.path("/query/multi"), { body })
  }
}

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. Set api_key in the provider options in medusa-config.ts (e.g. from process.env.MEDUSA_SEARCH_API_KEY)
2. Add the variable to your .env / deployment environment and restart Medusa
3. Confirm the key comes from the Medusa cloud search service dashboard and is not empty

Example fix

// before
resolve: [
  {
    resolve: "@medusajs/search-medusa",
    options: { endpoint: process.env.SEARCH_ENDPOINT, environment_handle: "..." },
  },
]
// after
resolve: [
  {
    resolve: "@medusajs/search-medusa",
    options: {
      api_key: process.env.MEDUSA_SEARCH_API_KEY,
      endpoint: process.env.SEARCH_ENDPOINT,
      environment_handle: process.env.SEARCH_ENV_HANDLE,
    },
  },
]

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

const hasValidSearchConfig = (opts) =>
  Boolean(opts?.api_key && opts?.endpoint && opts?.environment_handle)

When it happens

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

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

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• Medusa search requires an explicit "endpoint" provider optio
• Medusa search requires an explicit "environment_handle" prov
• 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/f59d936c644044f5. Report an issue: GitHub.