eyaltoledano/claude-task-master · error · Error

Tag name is required and must be a string

Error message

Tag name is required and must be a string

What it means

In the file-based branch of createTag, the tag name is validated for presence and type before any file operations. A missing, null, or non-string tagName throws this error. It is the first line of defense for tag-name input validation.

Source

Thrown at scripts/modules/task-manager/tag-management.js:86

	});

	// If remote handled it, return the result
	if (remoteResult) {
		if (!remoteResult.success) {
			throw new Error(remoteResult.message || 'Remote tag creation failed');
		}
		if (outputFormat === 'json') {
			return remoteResult;
		}
		// For text output, the bridge already displayed the message
		return remoteResult;
	}

	// Otherwise, continue with file-based logic below
	try {
		// Validate tag name
		if (!tagName || typeof tagName !== 'string') {
			throw new Error('Tag name is required and must be a string');
		}

		// Validate tag name format (alphanumeric, hyphens, underscores only)
		if (!/^[a-zA-Z0-9_-]+$/.test(tagName)) {
			throw new Error(
				'Tag name can only contain letters, numbers, hyphens, and underscores'
			);
		}

		// Reserved tag names
		const reservedNames = ['master', 'main', 'default'];
		if (reservedNames.includes(tagName.toLowerCase())) {
			throw new Error(`"${tagName}" is a reserved tag name`);
		}

		logFn.info(`Creating new tag: ${tagName}`);

		// Read current tasks data

View on GitHub (pinned to c0c98d367c)

Solutions

1. Pass a non-empty string as tagName, e.g. createTag(tasksPath, 'feature-x', options)
2. Validate CLI flags: ensure --name is provided on 'task-master add-tag'
3. In scripts, default/normalize the name: const name = String(rawName || '').trim()

Example fix

// before
await createTag(tasksPath, opts.tag, {}); // opts.tag undefined
// after
if (!opts.tag) throw new Error('--name is required');
await createTag(tasksPath, String(opts.tag), {});

if (typeof tagName !== 'string' || tagName.trim() === '') {
  throw new Error('tagName must be a non-empty string');
}

function isNonEmptyString(v) {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  await createTag(tasksPath, tagName, {});
} catch (err) {
  if (err.message === 'Tag name is required and must be a string') {
    console.error('Provide --name, e.g. task-master add-tag --name my-tag');
  } else throw err;
}

When it happens

Trigger: Calling createTag(undefined, ...) or createTag(null, ...), passing a non-string (number/object) tagName, or CLI/MCP callers forwarding an empty --name flag.

Common situations: Scripted automation passing variables that resolve to undefined; Commander option omitted so name is undefined; JSON payloads to the MCP tool missing the tagName field.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• streamObjectService requires a schema parameter
• Invalid task ID format: "${trimmedId}". Expected format: "15
• Empty file path provided
• Either existingTaskId or newSubtaskData must be provided
• INVALID_TASKS_FILE

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/20103f63fe68cfa5. Report an issue: GitHub.