JuliusBrussee/caveman · error

cave_tool_input_schema_mismatch

cave_tool_input_schema_mismatch

Error message

cave_tool_input_schema_mismatch:${options.name}

What it means

Thrown at execution time (not build time) when a tool built with a Standard Schema input receives arguments that fail validation: standard.validate(value) returned issues, so execute() refuses to hand unvalidated input to your implementation, throwing cave_tool_input_schema_mismatch:<toolName>. This is the runtime guard that your tool's execute only ever sees schema-valid values. The tool name is embedded after the colon so a multi-tool run can identify the offender.

Source

Thrown at packages/agent/src/primitives.ts:188

  }
  const definition = {
    kind: "tool",
    name: options.name,
    description: options.description,
    input,
    effect: options.effect,
    result,
    ...(typeof options.result === "object" ? { artifact: options.result } : {}),
    ...(options.allowRepeat === undefined ? {} : { allowRepeat: options.allowRepeat }),
    timeoutMs,
    ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
    async execute(value: unknown, signal?: AbortSignal) {
      if (standard === undefined) {
        return options.execute(value as never, signal);
      }
      const validated = await standard.validate(value);
      if (validated.issues) {
        throw new Error(`cave_tool_input_schema_mismatch:${options.name}`);
      }
      return options.execute(validated.value, signal);
    },
  } as const;
  Object.defineProperty(
    definition,
    Symbol.for("@caveman-ai/agent:tool-implementation-source"),
    {
      value: Function.prototype.toString.call(options.execute),
      enumerable: false,
      configurable: false,
      writable: false,
    },
  );
  return Object.freeze(definition);
}

function standardToolSchema(

View on GitHub (pinned to 766dce6b13)

Solutions

1. Compare the failing arguments against the tool's input schema and fix whichever is wrong — usually the prompt/example or the schema's required/typing.
2. If you call execute() yourself, validate first or catch this error and correct the arguments.
3. In a custom runner, catch it and return the mismatch message to the model as a tool error so it can retry with corrected arguments.

Example fix

// before (custom runner lets the throw escape)
const out = await def.execute(modelArgs);

// after (surface to the model for self-correction)
try {
  const out = await def.execute(modelArgs);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("cave_tool_input_schema_mismatch:")) {
    return { error: `arguments rejected by schema for ${e.message.split(":")[1]}; fix and retry` };
  }
  throw e;
}

// Validate before calling execute when driving tools manually.
const result = await standard.validate(args);
if (result.issues) {
  // fix args or reject before execute() throws cave_tool_input_schema_mismatch:<name>
}

try {
  const out = await def.execute(args, signal);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("cave_tool_input_schema_mismatch:")) {
    const toolName = e.message.split(":")[1];
    return { error: `invalid arguments for ${toolName}; correct and retry` };
  }
  throw e;
}

When it happens

Trigger: The model emits arguments that don't match the advertised schema (missing required field, wrong type, extra field with additionalProperties: false); a caller invoking definition.execute(rawArgs) directly with hand-built args; drift between the JSON Schema sent to the provider and the Standard Schema used to validate.

Common situations: Provider-side schema stripping (some APIs ignore parts of the schema); prompts that don't show the model the expected shape; tool schemas tightened in code while cached conversations still send the old shape.

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

• cave_context_ir_invalid
• tool_schema_transform_invalid:${segmentID}
• {path}: catalog must be a non-empty list
• {path}: every catalog row must be an object
• {label}: unknown field(s): {', '.join(sorted(unknown))}

AI-assisted analysis of JuliusBrussee/caveman@766dce6b13 (2026-08-18). Data as JSON: /api/errors/584bddd94f505a51. Report an issue: GitHub.