JuliusBrussee/caveman · error · CaveRequestError

cave checkpoint response missing source_ref or messages

Error message

cave checkpoint response missing source_ref or messages

What it means

Error "cave checkpoint response missing source_ref or messages" thrown in JuliusBrussee/caveman.

Source

Thrown at packages/sdk/typescript/src/index.ts:860

      return `[cave-artifact id=${response.artifact_id} source=${options.source} type=${options.contentType ?? "application/json"}]\nsummary: artifact stored.\nretrieve: authenticated GET /sdk/v1/artifacts/${response.artifact_id} or trace.artifacts.get("${response.artifact_id}").\n[/cave-artifact]`;
    },
    get: async (artifactId: string): Promise<unknown> => artifactGet(this.cave, artifactId, this.workflow, this.traceContext())
  };

  context = {
    checkpoint: async (messages: unknown[], options: Record<string, unknown>) => request(this.cave, "/sdk/v1/checkpoints", { messages, options, workflow: this.workflow }, this.workflow, this.traceContext()),
    /**
     * Reverse a checkpoint `source_ref` back into the original context.
     *
     * GETs `/sdk/v1/checkpoints/{sourceRef}/expand`; the gateway returns the
     * stored `{ source_ref, version, messages, checkpoint }`. This is the other
     * half of `checkpoint()` — reversibility is mandatory: a checkpoint that
     * cannot be expanded is a bug.
     */
    expand: async (sourceRef: string) => {
      const response = await request(this.cave, `/sdk/v1/checkpoints/${encodeURIComponent(sourceRef)}/expand`, undefined, this.workflow, this.traceContext());
      if (typeof response.source_ref !== "string" || response.source_ref.trim() === "" || !Array.isArray(response.messages)) {
        throw new CaveRequestError(200, "/sdk/v1/checkpoints/{sourceRef}/expand", "cave checkpoint response missing source_ref or messages");
      }
      return response;
    }
  };
}

// ─── Runtime policy client ────────────────────────────────────────────────────

/** Schema version this client accepts; anything else is rejected (fail closed). */
const RUNTIME_POLICY_SCHEMA_VERSION = "caveman.runtime-policy.v1";

/** Runtime-policy envelopes are KB-sized; stop a hostile body after 1 MiB. */
const RUNTIME_POLICY_MAX_RESPONSE_BYTES = 1024 * 1024;

async function readRuntimePolicyResponseText(response: Response): Promise<string> {
  const contentLength = response.headers?.get?.("content-length");
  if (typeof contentLength === "string" && /^[0-9]+$/.test(contentLength) && Number(contentLength) > RUNTIME_POLICY_MAX_RESPONSE_BYTES) {
    await Promise.resolve(response.body?.cancel?.()).catch(() => undefined);

View on GitHub (pinned to 27d5a3981a)

Solutions

1. The cave checkpoint response lacked source_ref or messages; verify the server version and retry.

When it happens

Trigger: Thrown at packages/sdk/typescript/src/index.ts:860 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/6c1cd721f8641962. Report an issue: GitHub.