Session goal schema v

Error message

Session goal schema v{schema_version} is newer than supported v{CURRENT_SESSION_GOAL_SCHEMA_VERSION}

What it means

Session goal files carry a schema_version; SessionGoalState::validate rejects snapshots whose schema version is greater than the CURRENT_SESSION_GOAL_SCHEMA_VERSION this build supports. This is a forward-compatibility guard: files written by a newer Codewhale must not be misread by older binaries.

Solutions

Upgrade Codewhale to a version supporting the file's schema version.
Delete or archive the newer goal file so the session loads without it.
Manually edit the file to the older schema (only if you know the format) — otherwise prefer deleting.

Example fix

// before: running stable (supports v1) against a file from nightly
{"schema_version": 2, ...}
// after: upgrade codewhale, or remove the goal file
cargo install codewhale --locked  # newer version

Defensive patterns

Strategy: try-catch

Validate before calling

// compare versions before loading
// if goal.schema_version > supported_version { upgrade codewhale first }

Try / catch

match load_goal(path) {
    Err(e) if e.to_string().contains("newer than supported") => {
        eprintln!("file written by a newer Codewhale; upgrade before loading");
    }
    other => other?,
}

Prevention

Keep Codewhale versions aligned across machines sharing session state.
Avoid downgrading after newer versions wrote session data.
Check release notes for goal schema bumps before switching versions.

When it happens

Trigger: Loading a goal file written by a newer Codewhale release with a higher schema_version than the running binary supports.

Common situations: Downgrading Codewhale after using a newer version; syncing session state between machines with different versions; a beta/nightly wrote v2+ goals and stable now reads them.

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

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

Appendix: source

Thrown at crates/tui/src/session_manager.rs:811

            status,
            token_budget: snapshot.token_budget,
            tokens_used: snapshot.tokens_used,
            time_used_seconds: snapshot.time_used_seconds,
            continuation_count: snapshot.continuation_count,
            elapsed_seconds: snapshot.elapsed_seconds.unwrap_or_default(),
            pause_reason: snapshot.pause_reason,
            goal_id: snapshot.goal_id.clone(),
            last_gap_fingerprint: snapshot.last_gap_fingerprint.clone(),
            repeated_gap_count: snapshot.repeated_gap_count,
            last_gap_pass: snapshot.last_gap_pass,
        };
        state.validate()?;
        Ok(Some(state))
    }

    pub fn validate(&self) -> io::Result<()> {
        if self.schema_version > CURRENT_SESSION_GOAL_SCHEMA_VERSION {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!(
                    "Session goal schema v{} is newer than supported v{}",
                    self.schema_version, CURRENT_SESSION_GOAL_SCHEMA_VERSION
                ),
            ));
        }
        let objective = self.objective.trim();
        if objective.is_empty() || objective.chars().count() > MAX_SESSION_GOAL_OBJECTIVE_CHARS {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!(
                    "Session goal objective must contain 1..={MAX_SESSION_GOAL_OBJECTIVE_CHARS} characters"
                ),
            ));
        }
        if self
            .goal_id

View on GitHub (pinned to 73e0f67d83)