n8n-io/n8n · error · Error

Sub-agent task name must contain at least one alphanumeric c

Error message

Sub-agent task name must contain at least one alphanumeric character

What it means

Thrown by sanitizeSubAgentTaskName when the input string, after sanitization (trim, lowercase, replace non-alphanumeric runs with underscores, strip leading/trailing underscores, truncate to MAX_TASK_NAME_LENGTH), becomes empty. The task name forms part of the task path used for tracking and persistence, so at least one alphanumeric character is required.

Source

Thrown at packages/@n8n/agents/src/runtime/tools/sub-agent-task-path.ts:73

 * lowercase, collapse each run of non-alphanumerics into a single underscore,
 * strip leading/trailing underscores, and cap the length — producing segments
 * that are collision-resistant, log/URL-safe, and accepted by
 * {@link SUB_AGENT_TASK_PATH_PATTERN}.
 *
 * @throws if nothing alphanumeric survives (we refuse to build a nameless path).
 */
export function sanitizeSubAgentTaskName(taskName: string): string {
	const sanitized = taskName
		.trim()
		.toLowerCase()
		.replace(/[^a-z0-9]+/g, '_')
		.replace(/_+/g, '_')
		.replace(/^_+|_+$/g, '')
		.slice(0, MAX_TASK_NAME_LENGTH)
		.replace(/_+$/g, '');

	if (!sanitized) {
		throw new Error('Sub-agent task name must contain at least one alphanumeric character');
	}

	return sanitized;
}

/** Type guard: does this string match `/root` or `/root/<segment>`? */
export function isSubAgentTaskPath(value: string): value is SubAgentTaskPath {
	return SUB_AGENT_TASK_PATH_PATTERN.test(value);
}

/**
 * Assert (and type-narrow) that a string is a valid task path. Used to validate
 * paths that were constructed here or received from elsewhere before we rely on
 * their shape.
 */
export function assertSubAgentTaskPath(value: string): asserts value is SubAgentTaskPath {
	if (!isSubAgentTaskPath(value)) {
		throw new Error(`Invalid sub-agent task path: ${value}`);

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Validate that the task name contains at least one ASCII alphanumeric character before passing it to delegation.
2. Provide a fallback default task name if sanitization would produce an empty string.
3. Pre-filter the task name to strip non-alphanumeric characters and check for emptiness.

Example fix

// before
delegate({ taskName: '---!!!---', subAgentId: 'a' });
// after
const rawName = '---!!!---';
const safeName = /[a-z0-9]/i.test(rawName) ? rawName : 'task';
delegate({ taskName: safeName, subAgentId: 'a' });

function hasAlphanumeric(s: string): boolean {
  return /[a-z0-9]/i.test(s);
}
const taskName = hasAlphanumeric(rawName) ? rawName : 'untitled_task';

function isSanitizableTaskName(name: unknown): name is string {
  return typeof name === 'string' && /[a-z0-9]/i.test(name);
}

When it happens

Trigger: Passing a taskName to a delegation that consists entirely of whitespace, punctuation, emojis, or other non-alphanumeric characters. For example '!!!', ' ', '---', '🎵🎵', or a string that after sanitization only had leading/trailing underscores that got stripped.

Common situations: User-provided or LLM-generated task names that are decorative (emojis, symbols only). Empty or whitespace-only task names from upstream input. Task names derived from localized text that contains no ASCII alphanumeric characters.

Related errors

• Deferred tool name "${tool.name}" is reserved
• Duplicate deferred tool name "${tool.name}"
• Invalid delegate sub-agent tool name "${name}": must start w
• MCP tool "${name}" from ${source} has an invalid name
• MCP tool "${name}" from ${options.source} conflicts with "${

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