TencentCloud/TencentDB-Agent-Memory · error · ParamRegistryError

Invalid module name '${mod.module}': must match ${MODULE_RE}

Error message

Invalid module name '${mod.module}': must match ${MODULE_RE}

What it means

This error is thrown by buildRegistry when validating a module entry in the parameter registry file whose 'module' name does not match MODULE_RE. The library enforces a strict naming convention so module identifiers are consistent and safe to use as keys/paths. It is a ParamRegistryError raised during loadParamRegistry, so loading the registry fails until the name is corrected.

Source

Thrown at MemoryCore/src/metadata/config/param-registry.ts:87

}

/**
 * 从已解析的对象构建注册表（可用于测试）。
 */
export function buildRegistry(data: ConfigParamsFile): ConfigParamRegistry {
  if (!data.version || !Array.isArray(data.modules)) {
    throw new ParamRegistryError("Config params file must have 'version' and 'modules' array");
  }

  const registry: ConfigParamRegistry = new Map();
  const seenModules = new Set<string>();

  for (const mod of data.modules) {
    if (!mod.module || typeof mod.module !== "string") {
      throw new ParamRegistryError("Each module entry must have a 'module' string field");
    }
    if (!MODULE_RE.test(mod.module)) {
      throw new ParamRegistryError(
        `Invalid module name '${mod.module}': must match ${MODULE_RE}`,
      );
    }
    if (seenModules.has(mod.module)) {
      throw new ParamRegistryError(`Duplicate module '${mod.module}'`);
    }
    seenModules.add(mod.module);

    if (!mod.description) {
      throw new ParamRegistryError(`Module '${mod.module}' must have a description`);
    }
    if (!Array.isArray(mod.params) || mod.params.length === 0) {
      throw new ParamRegistryError(`Module '${mod.module}' must have at least one param`);
    }

    const seenParams = new Set<string>();
    for (const param of mod.params) {
      if (!param.param_name || typeof param.param_name !== "string") {

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Check the MODULE_RE definition at the top of param-registry.ts to see the exact allowed format
2. Rename the module in the registry file to match the pattern (usually lowercase snake_case)
3. Strip whitespace and illegal characters from the module name
4. Add a schema/pattern check to your editor or CI that validates module names against MODULE_RE before the registry is loaded

Example fix

// before
{ "module": "My-Module", "description": "...", "params": [ ... ] }
// after
{ "module": "my_module", "description": "...", "params": [ ... ] }

const MODULE_RE = /^[a-z][a-z0-9_]*$/; // match the library's definition
function isValidModuleName(name) {
  return typeof name === 'string' && MODULE_RE.test(name);
}
if (!data.modules.every(m => isValidModuleName(m.module))) {
  throw new Error('registry contains invalid module names');
}

function isValidModuleName(name) {
  return typeof name === 'string' && /^[a-z][a-z0-9_]*$/.test(name);
}

try {
  const registry = await loadParamRegistry();
} catch (e) {
  if (e instanceof ParamRegistryError && e.message.includes('Invalid module name')) {
    const bad = e.message.match(/'([^']+)'/)?.[1];
    console.error(`Fix module name '${bad}' to match the required pattern`);
  } else throw e;
}

When it happens

Trigger: loadParamRegistry parses a registry JSON where data.modules[i].module is set but fails the MODULE_RE regular expression test (e.g. contains spaces, uppercase, hyphens, or illegal characters allowed by the pattern).

Common situations: Hand-edited registry files with a module name like 'My Module' or 'my-module' when the pattern expects snake_case; renamed modules after a version change; copy-pasted names with trailing whitespace.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式 llm.
• teamId is required for an agent prompt setting
• [skill-worker-pool] concurrency must be positive integer, go
• EmbeddingService: dimensions is required for remote provider
• 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/0449e620a3390147. Report an issue: GitHub.