ruvnet/ruflo · error

[GUPP] State checksum mismatch - possible corruption. Procee

Error message

[GUPP] State checksum mismatch - possible corruption. Proceeding with caution.

What it means

Integrity check in loadState(): the persisted GUPP state file parsed and passed schema validation, but its recomputed checksum does not match the stored one — the file may be corrupted or hand-edited. The state is still returned (proceed with caution) rather than discarded.

Source

Thrown at v3/plugins/gastown-bridge/src/gupp/state.ts:390

 * @returns Loaded state or empty state if not found
 */
export async function loadState(
  statePath: string = DEFAULT_STATE_PATH
): Promise<GuppState> {
  try {
    const content = await fs.readFile(statePath, 'utf-8');
    const parsed = JSON.parse(content);

    // Validate state structure
    const validated = GuppStateSchema.parse(parsed);

    // Verify checksum if present
    if (validated.checksum) {
      // Destructure to omit checksum for verification
      const { checksum: _, ...stateWithoutChecksum } = validated;
      const expectedChecksum = calculateChecksum(stateWithoutChecksum);
      if (validated.checksum !== expectedChecksum) {
        console.warn(
          '[GUPP] State checksum mismatch - possible corruption. Proceeding with caution.'
        );
      }
    }

    return validated as GuppState;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
      // File doesn't exist, return empty state
      return createEmptyState();
    }

    // Log error and return empty state
    console.error('[GUPP] Failed to load state:', error);
    return createEmptyState();
  }
}

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Treat checksum mismatch as corruption: restore state from the last known-good snapshot or re-sync from source.
2. Investigate concurrent writers or partial writes that could corrupt the state file.
3. Add atomic write (write-temp-then-rename) to state persistence to prevent torn writes.

When it happens

Trigger: Persisted GUPP state fails checksum verification on load: partial write, disk corruption, or version skew; adapter proceeds cautiously rather than trusting the state.

Common situations: See trigger scenarios.

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/1b9ee4c34f9ddb44. Report an issue: GitHub.