Model output is missing required fields (identifier, whenToU

Error message

Model output is missing required fields (identifier, whenToUse, systemPrompt)

What it means

After confirming the model output is a JSON object, parseGeneratedAgentSpec verifies the three required string fields: identifier, whenToUse, and systemPrompt. If any is missing or not a string, this error is thrown. It enforces the schema contract for generated agent definitions before the spec is persisted.

Source

Thrown at packages/coding-agent/src/modes/components/agents-hub.ts:182

	const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
	if (fenceMatch?.[1]) return fenceMatch[1].trim();
	const start = raw.indexOf("{");
	const end = raw.lastIndexOf("}");
	if (start >= 0 && end >= start) return raw.slice(start, end + 1).trim();
	return raw.trim();
}

function parseGeneratedAgentSpec(raw: string): GeneratedAgentSpec {
	const parsed = JSON.parse(extractJsonObject(raw)) as Partial<GeneratedAgentSpec>;
	if (!parsed || typeof parsed !== "object") {
		throw new Error("Model output is not a JSON object");
	}
	if (
		typeof parsed.identifier !== "string" ||
		typeof parsed.whenToUse !== "string" ||
		typeof parsed.systemPrompt !== "string"
	) {
		throw new Error("Model output is missing required fields (identifier, whenToUse, systemPrompt)");
	}
	const identifier = parsed.identifier.trim();
	const whenToUse = parsed.whenToUse.trim();
	const systemPrompt = parsed.systemPrompt.trim();
	if (!IDENTIFIER_PATTERN.test(identifier)) {
		throw new Error("Generated identifier is invalid (must be lowercase kebab-case, 2+ words)");
	}
	if (!whenToUse.toLowerCase().startsWith("use this agent when")) {
		throw new Error("Generated whenToUse must start with 'Use this agent when...'");
	}
	if (!systemPrompt) {
		throw new Error("Generated systemPrompt is empty");
	}
	return { identifier, whenToUse, systemPrompt };
}

function matchAgent(agent: HubAgent, query: string): boolean {
	const text = `${agent.name} ${agent.description} ${SOURCE_LABEL[agent.source]} ${agent.overrideModel ?? ""}`;

View on GitHub (pinned to 9690622007)

Solutions

Retry the architect generation — partial output is often transient, especially if truncation was the cause.
Use a model with a larger output budget or ask for a more concise systemPrompt so all fields fit.
Reinforce the exact key names and types in the architect prompt (identifier/whenToUse/systemPrompt, all strings).

Example fix

// before (model output)
{"identifier":"code-reviewer","description":"reviews code"}
// after
{"identifier":"code-reviewer","whenToUse":"Use this agent when reviewing pull requests","systemPrompt":"You are a code reviewer..."}

Defensive patterns

Strategy: validation

Validate before calling

function specFieldsPresent(o: Record<string, unknown>): boolean {
  return typeof o.identifier === "string" && typeof o.whenToUse === "string" && typeof o.systemPrompt === "string";
}
const parsed = JSON.parse(raw);
if (!specFieldsPresent(parsed)) retryArchitect();

Type guard

function isGeneratedAgentSpec(v: unknown): v is GeneratedAgentSpec {
  return typeof v === "object" && v !== null && !Array.isArray(v) &&
    typeof (v as any).identifier === "string" &&
    typeof (v as any).whenToUse === "string" &&
    typeof (v as any).systemPrompt === "string";
}

Try / catch

try {
  const spec = parseGeneratedAgentSpec(raw);
} catch (err) {
  if (err.message.startsWith("Model output is missing required fields")) {
    return retryArchitect({ missingFieldsHint: true });
  } throw err;
}

Prevention

Include the exact key names and string types in the architect prompt.
Keep the systemPrompt request concise to avoid output truncation dropping fields.
Validate with a schema (zod/arktype) before consuming model JSON.

When it happens

Trigger: #runAgentCreationArchitect receives parsed JSON that is an object but lacks one/all of identifier, whenToUse, systemPrompt, or has one typed as non-string (e.g. null, number, nested object).

Common situations: Model returns partial JSON when it hits output limits (long systemPrompt truncated away); model uses alternate key names like 'name'/'description'; model omits fields it deemed optional.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/550ef62340f15428. Report an issue: GitHub.