n8n-io/n8n · error · Error

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

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.

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 " " is reserved
• Duplicate deferred tool name
• Invalid delegate sub-agent tool name
• MCP tool " " from conflicts with
• MCP tool " " from has an invalid name

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

Appendix: 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)