TencentCloud/TencentDB-Agent-Memory · error

EmbeddingService: apiKey is required for remote provider

Error message

EmbeddingService: apiKey is required for remote provider

What it means

The OpenAI-compatible remote EmbeddingService constructor validates its config before doing any work. An embedding client without an API key can never authenticate, so the constructor fails fast with this error instead of producing confusing HTTP 401s later. It is thrown only when the provider is remote (OpenAI-compatible) and config.apiKey is falsy.

Source

Thrown at MemoryCore/src/core/store/embedding.ts:416

    total_tokens: number;
  };
}

export class OpenAIEmbeddingService implements EmbeddingService {
  private readonly baseUrl: string;
  private readonly apiKey: string;
  private readonly model: string;
  private readonly dims: number;
  private readonly sendDimensions: boolean;
  private readonly providerName: string;
  private readonly proxyUrl?: string;
  private readonly maxInputChars?: number;
  private readonly timeoutMs: number;
  private readonly logger?: Logger;

  constructor(config: OpenAIEmbeddingConfig, logger?: Logger) {
    if (!config.apiKey) {
      throw new Error("EmbeddingService: apiKey is required for remote provider");
    }
    if (!config.baseUrl) {
      throw new Error("EmbeddingService: baseUrl is required for remote provider");
    }
    if (!config.model) {
      throw new Error("EmbeddingService: model is required for remote provider");
    }
    if (!config.dimensions || config.dimensions <= 0) {
      throw new Error("EmbeddingService: dimensions is required for remote provider (must be a positive integer)");
    }
    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
    this.apiKey = config.apiKey;
    this.model = config.model;
    this.dims = config.dimensions;
    this.sendDimensions = config.sendDimensions ?? true;
    this.providerName = config.provider || "openai";
    this.proxyUrl = config.proxyUrl?.trim() || undefined;
    this.maxInputChars = config.maxInputChars && config.maxInputChars > 0 ? config.maxInputChars : undefined;

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Set config.apiKey to a valid key for the remote provider before constructing EmbeddingService
2. Load the key from the environment (process.env.OPENAI_API_KEY) and check it is non-empty before construction
3. If embeddings are meant to be local, switch to the local provider config instead of OpenAIEmbeddingConfig

Example fix

// before
new EmbeddingService({ baseUrl: 'https://api.openai.com/v1', model: 'text-embedding-3-small', dimensions: 1536 })
// after
if (!process.env.OPENAI_API_KEY) throw new Error('OPENAI_API_KEY missing');
new EmbeddingService({ apiKey: process.env.OPENAI_API_KEY, baseUrl: 'https://api.openai.com/v1', model: 'text-embedding-3-small', dimensions: 1536 })

function assertEmbeddingConfig(cfg) {
  if (!cfg?.apiKey || !cfg.apiKey.trim()) throw new Error('apiKey is required');
  return cfg;
}
assertEmbeddingConfig(config);

function hasApiKey(cfg): cfg is Required<Pick<OpenAIEmbeddingConfig,'apiKey'>> & OpenAIEmbeddingConfig {
  return typeof cfg?.apiKey === 'string' && cfg.apiKey.trim().length > 0;
}

try {
  svc = new EmbeddingService(config, logger);
} catch (e) {
  if (String(e.message).includes('apiKey is required')) {
    throw new ConfigError('OPENAI_API_KEY not set; check env/config loading');
  }
  throw e;
}

When it happens

Trigger: Calling `new EmbeddingService(config)` (OpenAI-compatible remote provider) where config.apiKey is undefined, null, or an empty/whitespace string.

Common situations: Environment variable not loaded (e.g. OPENAI_API_KEY unset or .env not read before constructing), config object read from a JSON file where the apiKey field was renamed or omitted, or accidentally using the remote constructor for a local provider without supplying a key.

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

• EmbeddingService: baseUrl is required for remote provider
• EmbeddingService: model is required for remote provider
• EmbeddingService: dimensions is required for remote provider
• [skill-worker-pool] concurrency must be positive integer, go
• llm.provider=proxy 需要 memory 系统用户 key —— 请在 yaml metadata.sy

AI-assisted analysis of TencentCloud/TencentDB-Agent-Memory@3efcd317b8 (2026-09-01). Data as JSON: /api/errors/100a8c2c0806c272. Report an issue: GitHub.