unknown detail level %q; use one of: summary, tasks, subtask

Error message

unknown detail level %q; use one of: summary, tasks, subtasks, running, planned

What it means

The get_flow_status tool dispatches on action.Detail against five known levels: summary, tasks, subtasks, running, planned. Any other value falls through to the default branch, which reports the invalid value and lists the accepted ones. Unlike the parse error, the JSON was valid — only the enum value was wrong.

Source

Thrown at backend/pkg/tools/flow_manager.go:87

	if err := json.Unmarshal(args, &action); err != nil {
		return "", fmt.Errorf("failed to parse get_flow_status args: %w", err)
	}

	verbose := action.Verbose.Bool()

	switch action.Detail {
	case FlowStatusDetailSummary:
		return t.buildSummary(ctx, verbose)
	case FlowStatusDetailTasks:
		return t.buildTasksList(ctx, verbose)
	case FlowStatusDetailSubtasks:
		return t.buildSubtasksList(ctx, action.TaskID.PtrInt64(), verbose)
	case FlowStatusDetailRunning:
		return t.buildRunningInfo(ctx, verbose)
	case FlowStatusDetailPlanned:
		return t.buildPlannedList(ctx, action.TaskID.PtrInt64(), verbose)
	default:
		return "", fmt.Errorf("unknown detail level %q; use one of: summary, tasks, subtasks, running, planned", action.Detail)
	}
}

func (t *flowStatusTool) buildSummary(ctx context.Context, verbose bool) (string, error) {
	tasks, err := t.db.GetFlowTasks(ctx, t.flowID)
	if err != nil {
		return "", fmt.Errorf("failed to get flow tasks: %w", err)
	}

	subtasks, err := t.db.GetFlowSubtasks(ctx, t.flowID)
	if err != nil {
		return "", fmt.Errorf("failed to get flow subtasks: %w", err)
	}

	taskCounts := map[string]int{"created": 0, "running": 0, "waiting": 0, "finished": 0, "failed": 0}
	var activeTask *database.Task
	for i, task := range tasks {
		taskCounts[string(task.Status)]++

View on GitHub (pinned to ea665308ba)

Solutions

Set detail to exactly one of: summary, tasks, subtasks, running, planned (lowercase).
Check the error message — it enumerates the valid values for you.
If a broader overview is needed, use 'summary' (the default) or 'tasks' rather than an invented level.
For LLM callers, add the allowed enum values to the tool description/schema to prevent guessing.

Example fix

// before
{"detail": "overview"}

// after
{"detail": "summary"}

Defensive patterns

Strategy: validation

Validate before calling

var validDetails = map[string]bool{
	"summary": true, "tasks": true, "subtasks": true, "running": true, "planned": true,
}
func detailValid(d string) bool { return validDetails[strings.ToLower(d)] }

Try / catch

detail := strings.ToLower(action.Detail)
if !detailValid(detail) {
	return fmt.Errorf("detail must be one of summary, tasks, subtasks, running, planned; got %q", action.Detail)
}

Prevention

Use the enum constants (FlowStatusDetailSummary etc.) instead of raw strings at call sites
List allowed values in the tool description so LLM callers cannot guess
Normalize casing before sending since matching is case-sensitive
Add a schema enum constraint on the detail field

When it happens

Trigger: Calling get_flow_status with {"detail": "full"}, {"detail": "overview"}, {"detail": "STATUS"} (case-sensitive), or {"detail": ""}.

Common situations: LLM invents plausible-but-unsupported detail names ('all', 'overview', 'status'); shell wrappers uppercase enum values; a caller reuses detail values from a different tool with a similar-but-different enum; empty string when the field is set but never filled.

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 vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/8fd6d6583d0397c4. Report an issue: GitHub.