TencentCloud/TencentDB-Agent-Memory · error · LlmProviderResolveError

llm.provider=proxy 需要 memory 系统用户 key —— 请在 yaml metadata.sy

Error message

llm.provider=proxy 需要 memory 系统用户 key —— 请在 yaml metadata.systemUser.memory 或 env TDAI_MEMORY_SYSTEM_USER_KEY 配置

What it means

In proxy mode the default behavior (llm.proxy.useMemorySystemUserKey, default true) is to take the API key from env TDAI_MEMORY_SYSTEM_USER_KEY. This error is thrown when that env var is unset or whitespace-only. The message also points to the yaml alternative: metadata.systemUser.memory.

Source

Thrown at MemoryCore/src/adapters/standalone/llm-provider-resolver.ts:56

  if (provider !== "proxy") return llm;

  if (!llm.baseUrl) {
    throw new LlmProviderResolveError(
      "llm.provider=proxy 需要 llm.baseUrl 指向 context_proxy 根 URL",
    );
  }
  if (!instanceId || !instanceId.trim()) {
    throw new LlmProviderResolveError(
      "llm.provider=proxy 需要非空 instanceId，无法拼出 /proxy/<iid>/v1 路径",
    );
  }

  const useSystemUserKey = llm.proxy?.useMemorySystemUserKey ?? true;
  let effectiveApiKey = llm.apiKey;
  if (useSystemUserKey) {
    const envKey = process.env.TDAI_MEMORY_SYSTEM_USER_KEY?.trim();
    if (!envKey) {
      throw new LlmProviderResolveError(
        "llm.provider=proxy 需要 memory 系统用户 key —— " +
        "请在 yaml metadata.systemUser.memory 或 env TDAI_MEMORY_SYSTEM_USER_KEY 配置",
      );
    }
    if (!MEMORY_USER_KEY_RE.test(envKey)) {
      throw new LlmProviderResolveError(
        "memory 系统用户 key 必须匹配 sk-mem-[A-Za-z0-9_-]{32}",
      );
    }
    effectiveApiKey = envKey;
  }

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

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Export TDAI_MEMORY_SYSTEM_USER_KEY with a valid sk-mem-... key in the runtime environment
2. Or set it in yaml under metadata.systemUser.memory so gateway startup backfills the env
3. Or set llm.proxy.useMemorySystemUserKey=false and provide llm.apiKey explicitly
4. Verify with printenv/echo in the same process that the var is actually visible

Example fix

// before
llm: { provider: "proxy", baseUrl: "http://proxy:8080" }
// after
// env: TDAI_MEMORY_SYSTEM_USER_KEY=sk-mem-0123456789abcdef0123456789abcdef
llm: { provider: "proxy", baseUrl: "http://proxy:8080" } // key now read from env

if (llm.provider === "proxy" && (llm.proxy?.useMemorySystemUserKey ?? true) && !process.env.TDAI_MEMORY_SYSTEM_USER_KEY?.trim()) {
  throw new Error("TDAI_MEMORY_SYSTEM_USER_KEY must be set for llm.provider=proxy");
}

null

try {
  const runtimeLlm = resolveStandaloneLlmForRuntime(llm, instanceId);
} catch (e) {
  if (e instanceof LlmProviderResolveError && e.message.includes("TDAI_MEMORY_SYSTEM_USER_KEY")) {
    logger.error("set TDAI_MEMORY_SYSTEM_USER_KEY or yaml metadata.systemUser.memory");
  }
  throw e;
}

When it happens

Trigger: provider="proxy" with baseUrl and instanceId set, useMemorySystemUserKey not set to false (or explicitly true), and process.env.TDAI_MEMORY_SYSTEM_USER_KEY missing/blank at resolve time.

Common situations: Env var not exported in the deployment environment (docker-compose/k8s secret not mounted); var defined in yaml metadata.systemUser.memory but gateway's applyMetadataEnvFromGatewayConfig was never applied in the standalone path; running locally without a .env file; typo in the env var name.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• memory 系统用户 key 必须匹配 sk-mem-[A-Za-z0-9_-]{32}
• llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式 llm.
• No upstream response available
• [instance-config] Config source returned empty VDB config fo
• teamId is required for an agent prompt setting

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