TencentCloud/TencentDB-Agent-Memory · error · MetadataError

invalid_param_scope

invalid_param_scope

Error message

module '${module}' param '${paramName}' is global-only, cannot set for user scope

What it means

setUserParam checks isUserWritable to enforce scope rules. If the parameter is defined but does not include 'user' in its allowed_scopes (i.e. it is global-only), the service refuses user-scope writes with invalid_param_scope. Global parameters can only be changed at global scope.

Source

Thrown at MemoryCore/src/metadata/service/config-param-service.ts:159

    }
    return num;
  }

  // ── 用户写入 ──

  async setUserParam(userId: string, module: string, paramName: string, value: string): Promise<ConfigParamEntity> {
    const moduleDef = getModuleDef(this.registry, module);
    if (!moduleDef) {
      throw new MetadataError("unknown_module", `unknown module: ${module}`);
    }

    const paramDef = getParamDef(this.registry, module, paramName);
    if (!paramDef) {
      throw new MetadataError("invalid_param_key", `unknown param: ${module}.${paramName}`);
    }

    if (!isUserWritable(this.registry, module, paramName)) {
      throw new MetadataError("invalid_param_scope", `module '${module}' param '${paramName}' is global-only, cannot set for user scope`);
    }

    this.validateParamValue(moduleDef, paramDef, value);

    const result = await this.store.upsertConfigParam({
      scope: "user",
      user_id: userId,
      module,
      param_name: paramName,
      param_value: value,
      description: paramDef.description,
    });

    this.invalidateUserCache(userId, module);
    return result;
  }

  // ── 配额 ──

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Set the parameter at global scope instead of user scope (use the global config update path).
2. Pick a different parameter that actually allows user scope (check allowed_scopes in the ParamDef).
3. If user-level overrides are genuinely needed, change the param definition to add 'user' to allowed_scopes in the registry.
4. Guard call sites: check isUserWritable(registry, module, paramName) before calling setUserParam.

Example fix

// before
await svc.setUserParam(userId, "system", "globalFlag", "1"); // global-only
// after — set globally instead
await svc.setGlobalParam("system", "globalFlag", "1");

import { isUserWritable } from "./registry";
if (!isUserWritable(registry, module, paramName)) {
  throw new Error(`${module}.${paramName} is global-only; set it at global scope`);
}
await svc.setUserParam(userId, module, paramName, value);

try {
  await svc.setUserParam(userId, module, paramName, value);
} catch (e) {
  if (e instanceof MetadataError && e.code === "invalid_param_scope") {
    await svc.setGlobalParam(module, paramName, value); // fall back to global scope
    return;
  }
  throw e;
}

When it happens

Trigger: setUserParam(userId, module, paramName, value) where the ParamDef's allowed_scopes does not include 'user' — the param is meant to be configured only globally.

Common situations: Attempting per-user overrides of a system-wide setting (e.g. a global feature flag or quota), or copy-pasting a per-user config call for a param that is global-only by design.

Related errors

• redis config is required when state_backend=redis
• [state-backend] Redis integration is not available — install
• invalid_param_value
• unknown_module
• permission_denied

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