TencentCloud/TencentDB-Agent-Memory · error · LlmProviderResolveError

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

Error message

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

What it means

When proxy mode opts out of the memory system user key (llm.proxy.useMemorySystemUserKey=false), the code relies solely on llm.apiKey. This error is thrown when neither path produced a key: useMemorySystemUserKey is false and llm.apiKey is unset/empty.

Source

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

  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",
    );
  }

  const cleanBase = llm.baseUrl.replace(/\/+$/, "");
  return {
    ...llm,
    baseUrl: `${cleanBase}/proxy/${encodeURIComponent(instanceId)}/v1`,
    apiKey: effectiveApiKey,
  };
}

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Set llm.apiKey explicitly in the llm config when disabling useMemorySystemUserKey
2. Or remove useMemorySystemUserKey=false so the default (env TDAI_MEMORY_SYSTEM_USER_KEY) path is used
3. Note the option accepts a boolean; if it is a non-default object form in your version, check StandaloneLLMConfig in llm-runner.ts for the exact shape

Example fix

// before
llm: { provider: "proxy", baseUrl: "http://proxy:8080", proxy: { useMemorySystemUserKey: false } }
// after
llm: { provider: "proxy", baseUrl: "http://proxy:8080", apiKey: "sk-my-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) {
  return typeof llm.apiKey === "string" && llm.apiKey.length > 0;
}

try {
  const runtimeLlm = resolveStandaloneLlmForRuntime(llm, instanceId);
} catch (e) {
  if (e instanceof LlmProviderResolveError && e.message.includes("useMemorySystemUserKey=false")) {
    logger.error("set llm.apiKey or re-enable useMemorySystemUserKey");
  }
  throw e;
}

When it happens

Trigger: provider="proxy" with baseUrl and instanceId set, llm.proxy.useMemorySystemUserKey=false, and llm.apiKey undefined/empty (note: TDAI_MEMORY_SYSTEM_USER_KEY is intentionally ignored in this mode).

Common situations: Developer sets useMemorySystemUserKey=false expecting the env key to still be used; config sets useMemorySystemUserKey=false from a template but forgets the apiKey field; apiKey provided under a different key name in yaml.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• memory 系统用户 key 必须匹配 sk-mem-[A-Za-z0-9_-]{32}
• metadata.systemUser.memory.userKey 必须匹配 sk-mem-[A-Za-z0-9_-]
• llm.provider=proxy 需要 memory 系统用户 key —— 请在 yaml metadata.sy
• teamId is required for an agent prompt setting
• [skill-worker-pool] concurrency must be positive integer, go

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