mastra-ai/mastra · error

Provider ${normalizedConfig.providerId} does not have a URL

Error message

Provider ${normalizedConfig.providerId} does not have a URL configured

What it means

For registry providers that are neither openai nor google, the router falls back to an OpenAI-compatible client, which requires a base URL. If the GatewayRegistry entry for that provider has no url configured, the constructor throws because it has no endpoint to send requests to.

Source

Thrown at packages/core/src/llm/model/embedding-router.ts:254

        }
      }

      if (!apiKey) {
        const envVarDisplay = Array.isArray(providerConfig.apiKeyEnvVar)
          ? providerConfig.apiKeyEnvVar.join(' or ')
          : providerConfig.apiKeyEnvVar;
        throw new Error(`API key not found for provider ${normalizedConfig.providerId}. Set ${envVarDisplay}`);
      }

      // Initialize the provider model directly in constructor
      if (normalizedConfig.providerId === 'openai') {
        this.providerModel = createOpenAI({ apiKey }).embeddingModel(normalizedConfig.modelId);
      } else if (normalizedConfig.providerId === 'google') {
        this.providerModel = createGoogleGenerativeAI({ apiKey }).embeddingModel(normalizedConfig.modelId);
      } else {
        // Use OpenAI-compatible provider for other providers
        if (!providerConfig.url) {
          throw new Error(`Provider ${normalizedConfig.providerId} does not have a URL configured`);
        }
        this.providerModel = createOpenAICompatible({
          name: normalizedConfig.providerId,
          apiKey,
          baseURL: providerConfig.url,
        }).embeddingModel(normalizedConfig.modelId);
      }
    }

    // Copy properties from the provider model if available
    if (this.providerModel.maxEmbeddingsPerCall !== undefined) {
      this.maxEmbeddingsPerCall = this.providerModel.maxEmbeddingsPerCall;
    }
    if (this.providerModel.supportsParallelCalls !== undefined) {
      this.supportsParallelCalls = this.providerModel.supportsParallelCalls;
    }
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass an explicit url in the object config: { providerId, modelId, url: "https://your-endpoint/v1", apiKey }.
2. Fix the provider's registry entry to include the correct base url.
3. Switch to a fully registered provider (openai, google) if you didn't intend to use a custom endpoint.
4. Check for typos in the providerId that may match a stub/placeholder registry entry.

Example fix

// before
new EmbeddingRouter("custom-provider/embed-model");
// after
new EmbeddingRouter({
  providerId: "custom-provider",
  modelId: "embed-model",
  url: "https://api.custom-provider.com/v1",
  apiKey: process.env.CUSTOM_API_KEY,
});

const pc = GatewayRegistry.getInstance().getProviderConfig(providerId);
if (pc && !pc.url && providerId !== 'openai' && providerId !== 'google' && !config.url) {
  throw new Error(`Provider "${providerId}" has no registry URL; pass url in config`);
}

const hasEndpoint = (providerId, config) => Boolean(config?.url || GatewayRegistry.getInstance().getProviderConfig(providerId)?.url);

try {
  router = new EmbeddingRouter(config);
} catch (e) {
  if (e instanceof Error && e.message.includes('does not have a URL configured')) {
    console.error(`Add { url: "https://your-endpoint/v1" } to the config for ${config.providerId}`);
  } else throw e;
}

When it happens

Trigger: new EmbeddingRouter("some-compatible-provider/model-id") where the provider exists in the registry (so it passed the unknown-provider check) but its registry entry lacks a `url`, and no explicit url was supplied in config.

Common situations: Partially registered/custom providers; registry misconfiguration after editing gateway defaults; using a provider that requires an explicit url (self-hosted vLLM, Azure resource endpoint) without supplying it.

Related errors

• Unknown OAuth provider: ${providerId}
• Unknown provider: ${normalizedConfig.providerId}
• Missing environment variable ${envVarName} required to build
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/4fc51391752fd437. Report an issue: GitHub.