Hmbown/CodeWhale · error · Error

The recording segment is missing its starting checkpoint.

Error message

The recording segment is missing its starting checkpoint.

What it means

Version 2 recordings are segmented: they must include a start checkpoint with petCheckpointVersion 2 whose historyStart equals its tick, proving the segment records where its replay history begins. A v2 recording missing start, with a wrong checkpoint version, or with a start whose historyStart does not match its tick cannot be replayed from its origin and is rejected.

Solutions

1. Restore the missing/malformed start checkpoint from the archive or producer that created the segment.
2. Ensure start.petCheckpointVersion === 2 and start.historyStart === start.tick before restoring.
3. Re-export the segment via prepareSegment()/recording() from a live world.
4. If the recording is truly unsegmented, export it with petReplayVersion 1 instead.

Example fix

// before
{ petReplayVersion: 2, start: { petCheckpointVersion: 2, tick: 120, historyStart: 0, ... } } // historyStart mismatch
// after
{ petReplayVersion: 2, start: { petCheckpointVersion: 2, tick: 120, historyStart: 120, ... } }

if (r.petReplayVersion === 2) {
  if (!r.start || r.start.petCheckpointVersion !== 2 || r.start.historyStart !== r.start.tick)
    throw new Error('Segment lacks a valid v2 start checkpoint');
}

const hasV2Start = (r) =>
  r.petReplayVersion !== 2 || (!!r.start &&
    r.start.petCheckpointVersion === 2 &&
    r.start.historyStart === r.start.tick);

try {
  world = PetWorld.fromRecording(points, r);
} catch (err) {
  if (err.message === 'The recording segment is missing its starting checkpoint.')
    throw new Error('Segment file truncated: start checkpoint missing.');
  throw err;
}

When it happens

Trigger: Calling `PetWorld.fromRecording(points, r)` with r.petReplayVersion === 2 where r.start is absent, r.start.petCheckpointVersion is not 2, or r.start.historyStart !== r.start.tick.

Common situations: Truncating or trimming a segment file and dropping its start checkpoint; a producer bug failing to stamp petCheckpointVersion or historyStart; hand-editing ticks without updating historyStart.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid pet particle checkpoint.
• Invalid pet particle checkpoint.
• Invalid pet recording.
• Pet checkpoint does not match its recording.
• Pet checkpoint does not match its recording.

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/a41303101923b517. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/tui/pet_watch/pet-native.js:260

            ...(this.origin ? { start: { ...structuredClone(this.origin), hasTelemetry: this.hasTelemetry, history } } : {}),
            ...(withCheckpoint ? { checkpoint: { ...this.checkpoint(), history } } : {}) };
    }
    static fromRecording(points, value) {
        const r = value;
        if (!r || ![1, 2].includes(r.petReplayVersion) || !Array.isArray(r.tape) || !Array.isArray(r.interactions))
            throw new Error('Invalid pet recording.');
        const version = r.expressionVersion === undefined ? 1 : r.expressionVersion;
        if (![1, 2].includes(version))
            throw new Error('Unsupported pet expression version.');
        if (r.checkpoint !== undefined && !r.checkpoint || r.start !== undefined && !r.start)
            throw new Error('Invalid pet checkpoint.');
        for (const c of [r.start, r.checkpoint])
            if (c && (c.sim?.expressionVersion ?? 1) !== version)
                throw new Error('Pet expression version does not match its checkpoint.');
        if (r.petReplayVersion === 1 && (r.start || r.checkpoint && r.checkpoint.petCheckpointVersion !== 1))
            throw new Error('Invalid legacy pet recording.');
        if (r.petReplayVersion === 2 && (!r.start || r.start.petCheckpointVersion !== 2 || r.start.historyStart !== r.start.tick))
            throw new Error('The recording segment is missing its starting checkpoint.');
        const first = r.start && PetWorld.restore(points, r.tape, r.interactions, r.start);
        const world = r.checkpoint ? PetWorld.restore(points, r.tape, r.interactions, r.checkpoint) : first ?? new PetWorld(points, r.tape, r.interactions, version);
        if (first) {
            if (!world.segmented || world.tick < first.tick || r.checkpoint && r.checkpoint.historyStart !== first.tick)
                throw new Error('Pet segment checkpoints do not agree.');
            world.origin = first.checkpoint();
        }
        return world;
    }
    /** Retire only consumed input. The exact origin makes each archived segment
     * independently replayable; no particle, random stream or score is reset. */
    prepareSegment() {
        const dropTape = Math.max(0, this.bucketIndex), dropInputs = this.interactionIndex, previous = this.origin;
        const tape = this.tapeLog.slice(dropTape), interactions = this.interactionLog.slice(dropInputs);
        const points = this.sim.p.map(p => [p.hx, p.hy]);
        const c = this.checkpoint();
        c.petCheckpointVersion = 2;
        c.historyStart = this.tick;

View on GitHub (pinned to 73e0f67d83)