What causes "Detail level must be one of: ${validDetailLevels.join(', ')}" in eyaltoledano/claude-task-master?

Use one of the levels named in the error message exactly (e.g. 'low', 'medium', 'high')

eyaltoledano/claude-task-master · warning

INVALID_PARAMETER

INVALID_PARAMETER

Error message

Detail level must be one of: ${validDetailLevels.join(', ')}

What it means

researchDirect accepts a constrained `detailLevel` enum (e.g. low/medium/high). If the supplied value is not one of the valid detail levels, the function returns INVALID_PARAMETER listing the allowed values, guarding the downstream prompt/API from unsupported settings.

Source

Thrown at mcp-server/src/core/direct-functions/research.js:93

			: [];

		// Parse comma-separated file paths if provided
		const parsedFilePaths = filePaths
			? filePaths
					.split(',')
					.map((path) => path.trim())
					.filter((path) => path.length > 0)
			: [];

		// Validate detail level
		const validDetailLevels = ['low', 'medium', 'high'];
		if (!validDetailLevels.includes(detailLevel)) {
			log.error(`Invalid detail level: ${detailLevel}`);
			disableSilentMode();
			return {
				success: false,
				error: {
					code: 'INVALID_PARAMETER',
					message: `Detail level must be one of: ${validDetailLevels.join(', ')}`
				}
			};
		}

		log.info(
			`Performing research query: "${query.substring(0, 100)}${query.length > 100 ? '...' : ''}", ` +
				`taskIds: [${parsedTaskIds.join(', ')}], ` +
				`filePaths: [${parsedFilePaths.join(', ')}], ` +
				`detailLevel: ${detailLevel}, ` +
				`includeProjectTree: ${includeProjectTree}, ` +
				`projectRoot: ${projectRoot}`
		);

		// Prepare options for the research function
		const researchOptions = {
			taskIds: parsedTaskIds,
			filePaths: parsedFilePaths,

View on GitHub (pinned to c0c98d367c)

Solutions

Use one of the levels named in the error message exactly (e.g. 'low', 'medium', 'high')
Normalize the input to lowercase and trim before sending
Update the client/config to the current enum values if a version change renamed levels
Map or clamp unsupported custom levels to the nearest valid one in calling code

Example fix

// before
await client.callTool('research', { query: 'explain caching', detailLevel: 'verbose' });

// after
await client.callTool('research', { query: 'explain caching', detailLevel: 'high', projectRoot: '/project' });

Defensive patterns

Strategy: validation

Validate before calling

const validDetailLevels = ['low', 'medium', 'high'];
const normalized = typeof detailLevel === 'string' ? detailLevel.trim().toLowerCase() : undefined;
if (!validDetailLevels.includes(normalized)) {
  throw new Error(`detailLevel must be one of: ${validDetailLevels.join(', ')}`);
}

Type guard

function isValidDetailLevel(v) {
  return v === 'low' || v === 'medium' || v === 'high';
}

Try / catch

try {
  const res = await client.callTool('research', { query, detailLevel: normalized, projectRoot });
  if (res.error?.code === 'INVALID_PARAMETER') {
    console.error(res.error.message); // lists the allowed values
  }
} catch (e) {
  console.error('research failed:', e.message);
}

Prevention

Normalize case/whitespace on enum inputs before sending
Whitelist the level from config instead of accepting free text
Parse the allowed values from the tool schema rather than hardcoding a stale list
Map custom levels (e.g. 'verbose') onto the closest valid level in your wrapper

When it happens

Trigger: Calling research with detailLevel values like 'verbose', 'detailed', 'MED', 'low ', 2, or null when the tool schema expects one of the exact valid strings; clients built against an older enum set that has since changed.

Common situations: An LLM inventing a plausible but unsupported level word; case mismatch ('High' vs 'high'); whitespace or typo ('meduim'); automation reading detailLevel from config where a free-text value was stored; schema drift after a version upgrade added/renamed levels.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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