n8n-io/n8n · error · Error

Unknown agents module: "${moduleName}". ${validTokens ? `Val

Error message

Unknown agents module: "${moduleName}". ${validTokens ? `Valid tokens: ${validTokens}.` : 'No agents modules are currently supported.'}

What it means

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.

Source

Thrown at packages/@n8n/config/src/configs/agents.config.ts:23

/**
 * Known agent sub-feature modules. Add a token here to make it valid in
 * `N8N_AGENTS_MODULES`. The backend fails fast on unknown tokens so typos
 * surface at startup instead of silently disabling a feature.
 */
export const AGENTS_MODULE_NAMES = [] as const;

export type AgentsModuleName = (typeof AGENTS_MODULE_NAMES)[number];

class AgentsModuleArray extends CommaSeparatedStringArray<AgentsModuleName> {
	constructor(str: string) {
		super(str);

		for (const name of this) {
			const moduleName: string = name;
			if (!AGENTS_MODULE_NAMES.includes(name)) {
				const validTokens = AGENTS_MODULE_NAMES.join(', ');
				throw new Error(
					`Unknown agents module: "${moduleName}". ${
						validTokens
							? `Valid tokens: ${validTokens}.`
							: 'No agents modules are currently supported.'
					}`,
				);
			}
		}
	}
}

@Config
export class AgentsConfig {
	/** TTL in seconds for agent checkpoint records. Stale checkpoints older than this are pruned. */
	@Env('N8N_AGENTS_CHECKPOINT_TTL')
	checkpointTtlSeconds: number = 96 * Time.hours.toSeconds;

	/**

View on GitHub (pinned to 5ac6606e81)

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).

Example fix

// before
# .env
AGENTS_MODULES=cat-bot

// after
# .env — no agents modules are currently supported; omit the var
# AGENTS_MODULES=

Defensive patterns

Strategy: validation

Validate before calling

import { AGENTS_MODULE_NAMES } from '@n8n/config/.../agents.config';
const requested = (process.env.AGENS_MODULES ?? '').split(',').map(s => s.trim()).filter(Boolean);
const invalid = requested.filter(t => !AGENTS_MODULE_NAMES.includes(t as never));
if (invalid.length) {
  // do not start n8n; surface the invalid tokens
}

Type guard

function isAgentsModuleName(value: string): value is AgentsModuleName {
  return (AGENTS_MODULE_NAMES as readonly string[]).includes(value);
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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).

Related errors

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/2b812d6aff02c288. Report an issue: GitHub.