TencentCloud/TencentDB-Agent-Memory · error · LlmResolveError

llm.provider=proxy 且 useMemorySystemUserKey=true 需要 metadata

Error message

llm.provider=proxy 且 useMemorySystemUserKey=true 需要 metadata.systemUser.memory 完整配置（userId + userKey）

What it means

Startup validator validateLlmProviderConfig (called by start()) checks that when provider=proxy and useMemorySystemUserKey is true (the default), resolveMemorySystemUserConfig finds a complete metadata.systemUser.memory entry. If absent, the gateway refuses to start with this LlmResolveError.

Source

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

 * service 模式下 instanceId 每次请求才知道，启动期只校验 systemUser 是否合法。
 */
export function validateLlmProviderConfig(
  llm: StandaloneLLMConfig,
  metadata: GatewayMetadataConfig,
): void {
  if (llm.provider !== "proxy") return;

  if (!llm.baseUrl) {
    throw new LlmResolveError(
      "llm.provider=proxy 需要 llm.baseUrl 指向 context_proxy 根 URL",
    );
  }

  const useSystemUserKey = llm.proxy?.useMemorySystemUserKey ?? true;
  if (useSystemUserKey) {
    const memoryUser = resolveMemorySystemUserConfig(metadata);
    if (!memoryUser) {
      throw new LlmResolveError(
        "llm.provider=proxy 且 useMemorySystemUserKey=true 需要 " +
        "metadata.systemUser.memory 完整配置（userId + userKey）",
      );
    }
    if (!isValidMemorySystemUserKey(memoryUser.userKey)) {
      throw new LlmResolveError(
        "metadata.systemUser.memory.userKey 必须匹配 sk-mem-[A-Za-z0-9_-]{32}",
      );
    }
  } else if (!llm.apiKey) {
    throw new LlmResolveError(
      "llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式配置 llm.apiKey",
    );
  }
}

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Populate metadata.systemUser.memory with userId and userKey (userKey must match sk-mem-[A-Za-z0-9_-]{32}).
2. If you prefer direct credentials, set llm.proxy.useMemorySystemUserKey: false and provide llm.apiKey.
3. Confirm the metadata file/section actually loaded by the gateway is the one containing systemUser.

Example fix

// before
llm:
  provider: proxy
  baseUrl: http://127.0.0.1:8096
// after
llm:
  provider: proxy
  baseUrl: http://127.0.0.1:8096
metadata:
  systemUser:
    memory:
      userId: mem-system
      userKey: sk-mem-AbCdEf0123456789AbCdEf0123456789

const useSysKey = llm.proxy?.useMemorySystemUserKey ?? true;
if (llm.provider === 'proxy' && useSysKey && !(metadata.systemUser?.memory?.userId && metadata.systemUser?.memory?.userKey)) {
  throw new Error('Startup preflight: metadata.systemUser.memory (userId + userKey) required for provider=proxy');
}

function hasCompleteMemorySystemUser(metadata: unknown): metadata is { systemUser: { memory: { userId: string; userKey: string } } } {
  const m = (metadata as any)?.systemUser?.memory;
  return Boolean(m?.userId && m?.userKey);
}

try {
  await gateway.start();
} catch (err) {
  if (err instanceof LlmResolveError && err.message.includes('systemUser.memory')) {
    console.error('Add metadata.systemUser.memory (userId + userKey) or set useMemorySystemUserKey=false + llm.apiKey');
  }
  throw err;
}

When it happens

Trigger: Running start() with provider=proxy, no explicit useMemorySystemUserKey: false, and metadata.systemUser.memory missing or incomplete (no userId/userKey pair).

Common situations: Fresh deployments that configured llm.proxy but forgot the metadata.systemUser block; config split across files where metadata was loaded from a different source; upgrades introducing the system-user requirement on existing proxy configs.

Related errors

• llm.provider=proxy 需要 llm.baseUrl 指向 context_proxy 根 URL (如
• llm.provider=proxy 且 llm.proxy.useMemorySystemUserKey=true 需
• llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式配置 ll
• llm.provider=proxy 需要 llm.baseUrl 指向 context_proxy 根 URL
• cos.generationLogRetentionDays must be a non-negative intege

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