medusajs/medusa · critical · MedusaError

Medusa search requires an explicit "endpoint" provider optio

Error message

Medusa search requires an explicit "endpoint" provider option

What it means

The provider client requires a non-empty endpoint URL to know where to send requests. This INVALID_ARGUMENT error is thrown at construction when the endpoint provider option is absent or empty.

Source

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

    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. Add endpoint to the provider options (e.g. https://search.medusa.cloud or your provisioned URL)
2. Set the backing environment variable in .env / hosting environment and restart
3. Double-check the variable name in medusa-config matches the one in .env exactly

Example fix

// before
options: { api_key: process.env.SEARCH_API_KEY }
// after
options: {
  api_key: process.env.SEARCH_API_KEY,
  endpoint: process.env.SEARCH_ENDPOINT ?? "https://search.medusa.csord.net",
}

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

const isValidEndpoint = (v) =>
  typeof v === "string" && /^https?:\/\/.+/.test(v)

When it happens

Trigger: Configuring the search-medusa provider in medusa-config without an endpoint option, or with a typo'd/empty environment variable such as process.env.MEDUSA_SEARCH_ENDPOINT when it is unset.

Common situations: Copy-pasting a provider config snippet that omits endpoint; missing SEARCH_ENDPOINT/MEDUSA_SEARCH_ENDPOINT env var in production while it existed locally; renaming the env var without updating the config.

Related errors

• Medusa search requires an explicit "api_key" provider option
• 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/08676ec602efc0ae. Report an issue: GitHub.