Install-state checkpoint also failed

Error message

${error.message} Install-state checkpoint also failed: ${checkpointError.message}

What it means

applyInstallPlanLocked writes an install-state checkpoint after operations so state stays consistent with disk. If the original operation already failed and the checkpoint write also fails, the library wraps both failures into a single error preserving the original via cause, so you know the operation failed AND state could not be checkpointed.

Solutions

Read error.cause to see the original operation failure and fix that first (e.g. free disk space, fix permissions).
Fix the checkpoint failure separately: check write permissions and free space for the install-state location.
Re-run the install after resolving; verify install state matches what was actually written.

Example fix

// before
try { apply(plan) } catch (e) { console.log(e.message) } // truncated, hides cause
// after
try { apply(plan) } catch (e) { console.error(e.message, e.cause ?? e) }

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight writable state dir
fs.accessSync(stateDir, fs.constants.W_OK);
fs.statSync(stateDir);

Try / catch

try {
  await applyInstallPlan(plan);
} catch (e) {
  console.error(e.message);
  if (e.cause) console.error('root cause:', e.cause.message); // fix the original failure first
  throw e;
}

Prevention

Ensure disk space and write permissions for both destinations and the install-state directory.
Always inspect error.cause on aggregate installer errors.
Run installers as a user with write access to ~/.claude and the state location.

When it happens

Trigger: An operation in applyInstallPlanLocked throws, and the subsequent best-effort checkpoint of install state (recording writtenDestinations) throws as well — the aggregate error message concatenates both messages.

Common situations: Disk full or read-only filesystem causing both the operation and the state-file write to fail; permission problems on the state directory; the settings write failed due to lock contention and the state dir is also unwritable.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/435ba70634d5efcb. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/install/apply.js:631

            plan.installStatePath,
            stateWithContentDigests(
              preserveUnwrittenFiles(
                hookRemovalCount > 0 && completedHookRemovalCount === hookRemovalCount
                  ? migration.finalState
                  : migration.bridgeState,
                migration,
                writtenDestinations
              ),
              {
                ...appliedPlan,
                operations: appliedPlan.operations.filter(operation => (
                  writtenDestinations.has(operation.destinationPath)
                )),
              }
            )
          );
        } catch (checkpointError) {
          throw new Error(
            `${error.message} Install-state checkpoint also failed: ${checkpointError.message}`,
            { cause: error }
          );
        }
      }
      throw error;
    }
    let antigravityMigrationWarnings = [];
  try {
    const antigravityMigration = cleanupLegacyAntigravityInstall(appliedPlan);
    if (antigravityMigration.detected && !antigravityMigration.complete) {
      antigravityMigrationWarnings = [
        'Legacy Antigravity migration is incomplete. ECC preserved modified, unverifiable, or unmanaged content under .agent; review and move anything you want to keep, then rerun the Antigravity install.',
        ...(Array.isArray(antigravityMigration.warnings) ? antigravityMigration.warnings : []),
      ];
    }
  } catch (error) {
    antigravityMigrationWarnings = [

View on GitHub (pinned to 8321021c54)