affaan-m/ECC · error · Error

rollback requires --state

Error message

rollback requires --state

What it means

In scripts/codex/legacy-sync-state.js, the 'rollback' subcommand restores files recorded by a previous sync session. rollbackLegacyCodexSync needs the --state flag to locate the state file that lists what was changed, so readFlag returning undefined causes this throw. On success the script prints a JSON result; if the rollback could not fully revert, it sets process.exitCode = 1 instead of throwing.

Source

Thrown at scripts/codex/legacy-sync-state.js:48

    })}\n`);
    return;
  }
  if (command === 'record') {
    const statePath = readFlag(argv, '--state');
    const filePath = readFlag(argv, '--path');
    if (!statePath || !filePath) throw new Error('record requires --state and --path');
    recordLegacySyncPath({ statePath, filePath });
    return;
  }
  if (command === 'finalize') {
    const statePath = readFlag(argv, '--state');
    if (!statePath) throw new Error('finalize requires --state');
    finalizeLegacySyncState({ statePath });
    return;
  }
  if (command === 'rollback') {
    const statePath = readFlag(argv, '--state');
    if (!statePath) throw new Error('rollback requires --state');
    const result = rollbackLegacyCodexSync({ statePath });
    process.stdout.write(`${JSON.stringify(result)}\n`);
    if (result.status !== 'rolled-back') process.exitCode = 1;
    return;
  }
  throw new Error('Usage: legacy-sync-state.js <begin|record|finalize|rollback> [options]');
}

module.exports = { main, readFlag };

if (require.main === module) {
  try {
    main();
  } catch (error) {
    process.stderr.write(`[ecc-sync] ERROR: ${error.message}\n`);
    process.exit(1);
  }
}

View on GitHub (pinned to 06c5e118c4)

Solutions

1. Pass the same state file used with begin/record/finalize: `node scripts/codex/legacy-sync-state.js rollback --state <state-file>`
2. If the state file is gone, do not retry rollback; manually restore from your backup or re-run the sync and rollback again
3. Verify the state path exists (`ls <state-file>`) before invoking so a different file-not-found error is not confused with this one

Example fix

// before
node scripts/codex/legacy-sync-state.js rollback
// after
node scripts/codex/legacy-sync-state.js rollback --state .codex-sync-state.json

const i = process.argv.indexOf('--state');
const statePath = i !== -1 ? process.argv[i + 1] : null;
if (process.argv[2] === 'rollback' && !statePath) {
  console.error('rollback needs the --state file created by begin');
  process.exit(2);
}

try {
  main();
} catch (e) {
  if (/rollback requires --state/.test(e.message)) console.error('Re-run with: rollback --state <begin-state-file>');
  else throw e;
}

When it happens

Trigger: `node scripts/codex/legacy-sync-state.js rollback` with no flags; `rollback --state` where the value is missing because the flag is last; passing the flag in a form readFlag does not recognize (e.g. `--state=/path` if only space-separated values are supported).

Common situations: Undoing a Codex sync gone wrong in an unfamiliar shell where the state path variable was never exported; running rollback hours after begin and losing the state filename; CI scripts that assume rollback needs no arguments.

Related errors

• finalize requires --state
• Invalid ${flag}: expected a single cache path segment
• Unknown argument: ${arg}
• Missing value for ${arg}
• begin requires --codex-home and --backup-dir

AI-assisted analysis of affaan-m/ECC@06c5e118c4 (2026-08-18). Data as JSON: /api/errors/7a96bb6decf1a688. Report an issue: GitHub.