affaan-m/ECC · error

Invalid install-state

Error message

Invalid install-state (${label}): ${details}

What it means

The persisted install-state failed schema validation. The message includes a label identifying which state blob was validated and details of each validation error (JSON path + message from the validator's errors array).

Solutions

1. Compare the reported instancePath details against the state schema and fix the offending fields
2. Delete the invalid state and reinstall to regenerate a valid one
3. Align installer versions so writer and validator agree on the schema
4. Restore the state file from a backup taken before the corruption

Example fix

// before: state missing request field
{ "operations": [...] }
// after: conforming to schema
{ "request": { "legacyMode": false }, "operations": [...] }

const validation = validateInstallState(record.state);
if (validation.errors?.length) {
  console.error(validation.errors.map(e => `${e.instancePath || '/'} ${e.message}`).join('; '));
  throw new Error('fix install-state before proceeding');
}

function isValidInstallState(state) { return validateInstallState(state).errors == null || validateInstallState(state).errors.length === 0; }

try { loadAndUseState(record); } catch (e) { if (String(e.message).startsWith('Invalid install-state')) { await reinstallToRegenerateState(); } else throw e; }

When it happens

Trigger: Loading an install-state record whose `state` does not conform to the expected schema — missing required fields, wrong types, unexpected extra/renamed properties after a version change.

Common situations: Manually editing the state file; state written by a different installer version; truncated or corrupted state after a crash; hand-crafted state for testing.

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

• -32602
• A normalized install request is required
• artifact path must be a non-empty relative path
• assets must be a nonempty list
• built an invalid spec

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

Appendix: source

Thrown at scripts/lib/install-lifecycle.js:1871

      id: record.adapter.id,
      target: record.adapter.target,
      kind: record.adapter.kind,
      root: record.targetRoot,
      installStatePath: record.installStatePath
    }
  };
}

function assertValidInstallStateForWrite(state, label) {
  const validation = validateInstallState(state);
  if (validation.valid) {
    return;
  }

  const details = validation.errors
    .map(error => `${error.instancePath || '/'} ${error.message}`)
    .join('; ');
  throw new Error(`Invalid install-state (${label}): ${details}`);
}

function writeRefreshedInstallState(record, statePreview) {
  const trustedStatePreview = buildAdapterDerivedStatePreview(statePreview, record);
  const stateWithCurrentDigests = {
    ...trustedStatePreview,
    operations: (trustedStatePreview.operations || []).map(operation => {
      if (!operation.destinationPath) {
        return { ...operation };
      }
      try {
        const contentSha256 = crypto.createHash('sha256')
          .update(readFileNoFollow(operation.destinationPath))
          .digest('hex');
        return { ...operation, contentSha256 };
      } catch (_error) {
        const { contentSha256: _staleDigest, ...operationWithoutDigest } = operation;
        return operationWithoutDigest;

View on GitHub (pinned to 8321021c54)