{"record":{"id":"93579e48f993cb27","repo":"affaan-m/ECC","slug":"invalid-install-state-label-details","errorCode":null,"errorMessage":"Invalid install-state (${label}): ${details}","messagePattern":"Invalid install-state \\((.+?)\\): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/install-lifecycle.js","lineNumber":1375,"sourceCode":"      id: record.adapter.id,\n      target: record.adapter.target,\n      kind: record.adapter.kind,\n      root: record.targetRoot,\n      installStatePath: record.installStatePath\n    }\n  };\n}\n\nfunction assertValidInstallStateForWrite(state, label) {\n  const validation = validateInstallState(state);\n  if (validation.valid) {\n    return;\n  }\n\n  const details = validation.errors\n    .map(error => `${error.instancePath || '/'} ${error.message}`)\n    .join('; ');\n  throw new Error(`Invalid install-state (${label}): ${details}`);\n}\n\nfunction writeRefreshedInstallState(record, statePreview) {\n  const trustedStatePreview = buildAdapterDerivedStatePreview(statePreview, record);\n  assertValidInstallStateForWrite(trustedStatePreview, record.installStatePath);\n  return writeContainedFile(\n    record.installStatePath,\n    formatJson(trustedStatePreview),\n    record.targetRoot,\n    'repair'\n  );\n}\n\nfunction prepareRepairMigration(plan, record) {\n  const trustedPlan = {\n    ...plan,\n    adapter: record.adapter,\n    targetRoot: record.targetRoot,","sourceCodeStart":1357,"sourceCodeEnd":1393,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/install-lifecycle.js#L1357-L1393","documentation":"Before writing a refreshed install-state, assertValidInstallStateForWrite runs validateInstallState (JSON-schema validation) and rejects if any errors are returned. The message lists each AJV-style error (instancePath + message) joined by semicolons. This stops the installer from persisting a state shape it cannot later trust.","triggerScenarios":"Calling writeRefreshedInstallState (during repair) or any path through assertValidInstallStateForWrite when buildAdapterDerivedStatePreview produces a state that fails the schema — e.g. missing required fields, wrong types for target/operations, or an unknown operation kind after hydration.","commonSituations":"A bug in adapter derivation drops a required field; a migration path produces an operation not covered by the schema; manual edits to the state that survive initial read but fail revalidation on write; schema upgraded in lockstep with older state data.","solutions":["Read the `details` portion of the message — each entry's instancePath points at the failing field.","Fix the upstream producer of that field (adapter, migration, or prior install) so the value satisfies the schema.","If the state is unrecoverable, uninstall and re-install to regenerate it from scratch.","Report an installer bug if the state was produced by the installer itself (attach the listed instancePath/message)."],"exampleFix":"// before: state.target.root missing → '/target must NOT have required property root'\n// after: regenerate state\n./install.sh --target claude --uninstall\n./install.sh --target claude","handlingStrategy":"validation","validationCode":"function previewWillValidate(statePreview) {\n  const v = validateInstallState(statePreview);\n  return v.valid ? null : v.errors.map(e => `${e.instancePath || '/'} ${e.message}`).join('; ');\n}\n// before persisting refreshed state: assert previewWillValidate(state) === null","typeGuard":"function isValidInstallState(state) {\n  return validateInstallState(state).valid === true;\n}","tryCatchPattern":"try {\n  writeRefreshedInstallState(record, statePreview);\n} catch (err) {\n  if (err.message.startsWith('Invalid install-state')) {\n    // read instancePath details, fix upstream field, regenerate state\n  } else throw err;\n}","preventionTips":["Treat the install-state schema as a strict contract — match it when generating fields.","Run the project's state validator in tests for any code that builds state previews.","Upgrade installer and state together to avoid schema drift.","Back up state before migrations so a bad write can be rolled back."],"tags":["repair","install","validation","schema","state"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}