{"record":{"id":"2b812d6aff02c288","repo":"n8n-io/n8n","slug":"unknown-agents-module-modulename-validtok","errorCode":null,"errorMessage":"Unknown agents module: \"${moduleName}\". ${validTokens ? `Valid tokens: ${validTokens}.` : 'No agents modules are currently supported.'}","messagePattern":"Unknown agents module: \"(.+?)\"\\. (.+?)\\.` : 'No agents modules are currently supported\\.'\\}","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/config/src/configs/agents.config.ts","lineNumber":23,"sourceCode":"\n/**\n * Known agent sub-feature modules. Add a token here to make it valid in\n * `N8N_AGENTS_MODULES`. The backend fails fast on unknown tokens so typos\n * surface at startup instead of silently disabling a feature.\n */\nexport const AGENTS_MODULE_NAMES = [] as const;\n\nexport type AgentsModuleName = (typeof AGENTS_MODULE_NAMES)[number];\n\nclass AgentsModuleArray extends CommaSeparatedStringArray<AgentsModuleName> {\n\tconstructor(str: string) {\n\t\tsuper(str);\n\n\t\tfor (const name of this) {\n\t\t\tconst moduleName: string = name;\n\t\t\tif (!AGENTS_MODULE_NAMES.includes(name)) {\n\t\t\t\tconst validTokens = AGENTS_MODULE_NAMES.join(', ');\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Unknown agents module: \"${moduleName}\". ${\n\t\t\t\t\t\tvalidTokens\n\t\t\t\t\t\t\t? `Valid tokens: ${validTokens}.`\n\t\t\t\t\t\t\t: 'No agents modules are currently supported.'\n\t\t\t\t\t}`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n}\n\n@Config\nexport class AgentsConfig {\n\t/** TTL in seconds for agent checkpoint records. Stale checkpoints older than this are pruned. */\n\t@Env('N8N_AGENTS_CHECKPOINT_TTL')\n\tcheckpointTtlSeconds: number = 96 * Time.hours.toSeconds;\n\n\t/**","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/config/src/configs/agents.config.ts#L5-L41","documentation":"Thrown by AgentsModuleArray's constructor in @n8n/config when parsing the AGENTS_MODULES env var. AGENTS_MODULE_NAMES is declared as `[] as const`, so the set of valid tokens is currently empty — ANY non-empty value supplied for the config key trips this error. The error message interpolates the offending moduleName and the (currently empty) list of valid tokens.","triggerScenarios":"Setting `AGENTS_MODULES=foo` (or any value) in the environment or config file, then starting n8n. The CommaSeparatedStringArray parses the csv and validates each token against AGENTS_MODULE_NAMES; since that tuple is empty, every token fails the `.includes(name)` check.","commonSituations":"A user copies an env var from an internal/experimental doc that references an agents module that hasn't shipped yet; a typo; attempting to enable a feature gated behind a flag that the current build doesn't recognize; running a newer config on an older binary (or vice versa).","solutions":["Unset AGENTS_MODULES (or leave it empty) — no agents modules are currently supported, so any non-empty value is invalid.","Verify the build matches the doc: grep `AGENTS_MODULE_NAMES =` to confirm whether any tokens were added since this snapshot.","If you intended to enable an experimental module, upgrade to a build where the module name appears in the AGENTS_MODULE_NAMES tuple, then set the var to that exact token.","Check for typos or stray whitespace in the env var value (the parser splits on commas, so trailing commas produce empty tokens)."],"exampleFix":"// before\n# .env\nAGENTS_MODULES=cat-bot\n\n// after\n# .env — no agents modules are currently supported; omit the var\n# AGENTS_MODULES=","handlingStrategy":"validation","validationCode":"import { AGENTS_MODULE_NAMES } from '@n8n/config/.../agents.config';\nconst requested = (process.env.AGENS_MODULES ?? '').split(',').map(s => s.trim()).filter(Boolean);\nconst invalid = requested.filter(t => !AGENTS_MODULE_NAMES.includes(t as never));\nif (invalid.length) {\n  // do not start n8n; surface the invalid tokens\n}","typeGuard":"function isAgentsModuleName(value: string): value is AgentsModuleName {\n  return (AGENTS_MODULE_NAMES as readonly string[]).includes(value);\n}","tryCatchPattern":null,"preventionTips":["Leave AGENTS_MODULES unset unless you have confirmed the token is in AGENTS_MODULE_NAMES for your build.","Add a startup self-check that validates env vars against the tuple before the app boots.","Track config changes across versions — agents module tokens can be added/removed."],"tags":["config","validation","agents","env","startup"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}