can1357/oh-my-pi · error · AIError.ValidationError

Validation failed for tool "${toolCall.name}":\n${errors}\n\

Error message

Validation failed for tool "${toolCall.name}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(receivedArgs, null, 2)}

What it means

Thrown as AIError.ValidationError when a tool call's arguments fail zod/JSON-schema validation in the AI layer. The message includes the list of validation issues, plus the (possibly truncated) received arguments, so the developer can see exactly which fields were wrong. This is the library's contract check that LLM-emitted tool arguments match the tool's declared parameter schema before execution.

Source

Thrown at packages/ai/src/utils/validation.ts:2064

	// Format validation errors nicely. The header phrase is asserted by
	// existing tests; the detailed body is informational.
	const errors = result.messages.join("\n") || "Unknown validation error";

	// Truncate long per-field strings: the full payload (potentially hundreds
	// of KB for write/edit-class calls) would otherwise round-trip back to the
	// model inside the tool error.
	const receivedArgs = changed
		? {
				original: truncateArgsForError(originalArgs),
				normalized: truncateArgsForError(normalizedArgs),
			}
		: truncateArgsForError(originalArgs);

	const errorMessage = `Validation failed for tool "${
		toolCall.name
	}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(receivedArgs, null, 2)}`;

	throw new AIError.ValidationError(errorMessage);
}

/**
 * Runs up to {@link MAX_COERCION_PASSES} issue-driven coercion rounds,
 * re-applying the schema normalizations after each round because a coercion
 * may unwrap JSON-string containers and expose fields the pre-validation
 * passes could not reach.
 */
function runCoercionPasses(
	ctx: ValidationContext,
	args: unknown,
	initial: ContextValidationResult,
): { args: unknown; result: ContextValidationResult; changed: boolean } {
	const { json } = ctx;
	let normalizedArgs = args;
	let result = initial;
	let changed = false;
	for (let pass = 0; pass < MAX_COERCION_PASSES; pass += 1) {

View on GitHub (pinned to 9690622007)

Solutions

Inspect the 'Received arguments' section of the message against the tool's schema to identify the mismatched field.
Loosen the tool schema (make fields optional, use unions/z.coerce) so valid-but-odd model output passes.
Improve the tool description and parameter descriptions so the model emits correct arguments.
Retry the request with a stronger model or ask the model to repair its tool arguments.

Example fix

// before: strict schema rejects string numbers from the model
const schema = z.object({ count: z.number() });
// after: coerce common LLM output shapes
const schema = z.object({ count: z.coerce.number() });

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-validate arguments before sending to the model loop
const parsed = tool.schema.safeParse(args);
if (!parsed.success) {
  console.warn("args will fail validation:", parsed.error.issues);
}

Type guard

function hasRequiredFields(args: Record<string, unknown>, req: readonly string[]): args is Record<string, unknown> & { [k: string]: unknown } {
  return req.every(k => k in args && args[k] !== undefined);
}

Try / catch

import { AIError } from "@oh-my-pi/pi-ai";
try {
  await agent.step();
} catch (err) {
  if (err instanceof AIError.ValidationError) {
    // err.message lists issues + received args; ask the model to repair
    await agent.retryWithCorrection(err.message);
  } else throw err;
}

Prevention

Write precise zod descriptions/enums so the model sees the expected shapes.
Prefer z.coerce for numeric/boolean fields LLMs often stringify.
Use stronger models for strict-schema tools.
Catch AIError.ValidationError and feed the issue list back for a repair round.

When it happens

Trigger: Calling agent/LLM completion with tool calling where the model emits arguments that don't satisfy the tool's schema: missing required fields, wrong types, extra unknown fields rejected by the schema, or JSON strings that can't be coerced after MAX_COERCION_PASSES rounds in validateToolCall.

Common situations: Weaker/smaller models hallucinating or omitting required parameters; schema changes in a tool after a model was prompted with a stale tool description; the model double-encoding JSON as strings; strict schemas (no coercion possible) fed to models prone to typo'd enum values.

Related errors

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