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

At execution time, a tool defined with a Standard Schema input validates the incoming arguments via standard.validate(value). If validation returns issues, execute() throws an error whose message is cave_tool_input_schema_mismatch:<toolName> — meaning the model/caller supplied arguments that do not conform to the tool's declared input schema.

Solutions

1. Log and inspect the failing value against the tool's input schema; fix the argument payload to satisfy the schema
2. Validate arguments with the same Standard Schema on the caller side before invoking execute()
3. If the schema changed, regenerate/repair callers (prompts, client code) to match the new required fields and types

Example fix

// before
await myTool.execute({ query: 123 }); // query must be a string
// after
const parsed = mySchema.safeParse({ query: 123 });
if (!parsed.success) throw new Error("bad tool args: " + parsed.error.message);
await myTool.execute({ query: "cave docs" });

const check = await standard["~standard"].validate(args);
if (check.issues) {
  throw new Error(`tool args invalid for ${toolName}: ` + JSON.stringify(check.issues));
}
await toolDef.execute(args, signal);

try {
  await toolDef.execute(args, signal);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("cave_tool_input_schema_mismatch:")) {
    const toolName = err.message.split(":")[1];
    // re-validate args against tool input schema, repair or reject the call
  } else throw err;
}

When it happens

Trigger: Calling toolDefinition.execute(value) with a value that fails the Standard Schema validation — missing required properties, wrong types, additional/unexpected fields the schema rejects.

Common situations: A language model hallucinating malformed tool arguments; a caller bypassing the provider layer and invoking execute() directly with hand-built payloads; schema tightened after callers were built against an older, looser schema.

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

• at least one report path and the canonical span fixture…
• canonical span
• cave_agent_definition_invalid
• cave_budget_release_reason_required
• cave_context_ir_invalid

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/584bddd94f505a51. Report an issue: GitHub.

Appendix: 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 3ee70a1026)