JuliusBrussee/caveman · error

caveman agent: file path is required

Error message

caveman agent: file path is required

What it means

The file() primitive constructs a frozen FileSource for the agent and validates its input up front. It throws when the path argument is not a non-empty string (after trimming whitespace). The library refuses to create a file source with no usable path so failures surface at the call site rather than deep in execution.

Solutions

1. Pass a non-empty string path to file(), e.g. file("src/config.json")
2. Check the variable feeding the path — read it from env/config with a default and trim it before calling
3. Convert non-string path values (URL, Buffer) to a string path first with String(url) or url.pathname

Example fix

// before
const src = file(process.env.CONFIG_PATH); // undefined -> throws
// after
const p = process.env.CONFIG_PATH?.trim();
if (!p) throw new Error("CONFIG_PATH not set");
const src = file(p);

function validFilePath(p: unknown): p is string {
  return typeof p === "string" && p.trim() !== "";
}
if (!validFilePath(rawPath)) throw new Error("path required");

function isNonEmptyString(v: unknown): v is string {
  return typeof v === "string" && v.trim().length > 0;
}

try {
  const src = file(path);
} catch (err) {
  if (err instanceof Error && err.message.includes("file path is required")) {
    // surface config problem: path was empty or not a string
  } else throw err;
}

When it happens

Trigger: file("") , file(" "), file(undefined as unknown as string), file(null), or any non-string value passed to file().

Common situations: Config/env variable that supplies the file path is unset or whitespace-only; a template/interpolation produced an empty string; a caller passed a Buffer, URL, or options object instead of a string path.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• at least one report path and the canonical span fixture…
• cannot remember empty text
• cannot supersede with empty text
• cave_budget_release_reason_required
• cave_subagent_arguments_invalid

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

Appendix: source

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

  StandardJSONSchemaV1,
  StandardSchemaV1,
} from "@standard-schema/spec";

export const AUTO = Symbol.for("@caveman-ai/agent:auto");
export type Auto = { readonly kind: "auto"; readonly [AUTO]: true };

export function auto(): Auto {
  return Object.freeze({ kind: "auto", [AUTO]: true as const });
}

export interface FileSource {
  readonly kind: "file";
  readonly path: string;
}

export function file(path: string): FileSource {
  if (typeof path !== "string" || path.trim() === "") {
    throw new Error("caveman agent: file path is required");
  }
  return Object.freeze({ kind: "file", path });
}

export const schema = {
  any: () => Type.Any(),
  array: <T extends TSchema>(items: T) => Type.Array(items),
  boolean: () => Type.Boolean(),
  integer: () => Type.Integer(),
  literal: <T extends string | number | boolean>(value: T) => Type.Literal(value),
  number: () => Type.Number(),
  object: <T extends Record<string, TSchema>>(properties: T) => Type.Object(properties),
  optional: <T extends TSchema>(value: T) => Type.Optional(value),
  string: () => Type.String(),
  union: <T extends TSchema[]>(values: [...T]) => Type.Union(values),
};

export type ToolEffect = "read" | "write" | "idempotent" | "external";

View on GitHub (pinned to 3ee70a1026)