TencentCloud/TencentDB-Agent-Memory · error · LlmResolveError

llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式配置 ll

Error message

llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式配置 llm.apiKey

What it means

If proxy.useMemorySystemUserKey is false (opting out of memory system-user auth), the resolver requires llm.apiKey to be explicitly configured — effectiveApiKey ends up undefined otherwise, and this LlmResolveError is thrown. The proxy call must carry some credential, and this path demands a direct key.

Source

Thrown at MemoryCore/src/gateway/llm-resolver.ts:84

  const useSystemUserKey = llm.proxy?.useMemorySystemUserKey ?? true;
  let effectiveApiKey = llm.apiKey;
  if (useSystemUserKey) {
    if (!memorySystemUser) {
      throw new LlmResolveError(
        "llm.provider=proxy 且 llm.proxy.useMemorySystemUserKey=true 需要 " +
        "metadata.systemUser.memory 完整配置（userId + userKey），当前缺失",
      );
    }
    if (!isValidMemorySystemUserKey(memorySystemUser.userKey)) {
      throw new LlmResolveError(
        "metadata.systemUser.memory.userKey 必须匹配 sk-mem-[A-Za-z0-9_-]{32}",
      );
    }
    effectiveApiKey = memorySystemUser.userKey;
  }

  if (!effectiveApiKey) {
    throw new LlmResolveError(
      "llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式配置 llm.apiKey",
    );
  }

  // baseUrl 拼接规则：去掉尾部斜杠，追加 /proxy/<iid>/v1
  const cleanBase = llm.baseUrl.replace(/\/+$/, "");
  const proxyBaseUrl = `${cleanBase}/proxy/${encodeURIComponent(instanceId)}/v1`;

  return {
    ...llm,
    baseUrl: proxyBaseUrl,
    apiKey: effectiveApiKey,
  };
}

/**
 * 只做校验、不返回配置 —— 用于启动期"fail-fast"检查。
 * standalone 模式下 instanceId 一般是 "default"，可以直接校验；

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Set llm.apiKey explicitly in the yaml (or wire the env var into it) when useMemorySystemUserKey is false.
2. Remove useMemorySystemUserKey: false (or set true) and instead configure metadata.systemUser.memory if you intended system-user auth.
3. Double-check yaml indentation so apiKey sits under llm:, not a sibling block.

Example fix

// before
llm:
  provider: proxy
  baseUrl: http://127.0.0.1:8096
  proxy:
    useMemorySystemUserKey: false
// after
llm:
  provider: proxy
  baseUrl: http://127.0.0.1:8096
  apiKey: sk-your-key
  proxy:
    useMemorySystemUserKey: false

if (llm.provider === 'proxy' && llm.proxy?.useMemorySystemUserKey === false && !llm.apiKey) {
  throw new Error('useMemorySystemUserKey=false requires an explicit llm.apiKey');
}

function hasExplicitApiKey(llm: { provider: string; apiKey?: string; proxy?: { useMemorySystemUserKey?: boolean } }): boolean {
  const useSysKey = llm.proxy?.useMemorySystemUserKey ?? true;
  return llm.provider !== 'proxy' || useSysKey || (typeof llm.apiKey === 'string' && llm.apiKey.length > 0);
}

try {
  gateway.start();
} catch (err) {
  if (err instanceof LlmResolveError && err.message.includes('llm.apiKey')) {
    console.error('Set llm.apiKey explicitly, or re-enable useMemorySystemUserKey with metadata.systemUser.memory configured');
  }
  throw err;
}

When it happens

Trigger: provider=proxy with llm.proxy.useMemorySystemUserKey: false and no llm.apiKey; also occurs when useMemorySystemUserKey=true but metadata.systemUser.memory is missing AND llm.apiKey is unset (effectiveApiKey still empty after the earlier throw path is bypassed by version differences).

Common situations: Operators disabling system-user auth assuming apiKey flows from elsewhere (env var never wired); migration from direct-provider mode where apiKey was removed along with the old provider config; typo in the apiKey field name.

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

• llm.provider=proxy 且 llm.proxy.useMemorySystemUserKey=true 需
• llm.provider=proxy 且 useMemorySystemUserKey=true 需要 metadata
• llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式 llm.
• llm.provider=proxy 需要 llm.baseUrl 指向 context_proxy 根 URL (如
• llm.provider=proxy 需要 instanceId，但 core 当前 instanceId 为空 ——

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