{"record":{"id":"2ca2f6428c4d0551","repo":"affaan-m/ECC","slug":"guided-install-failed","errorCode":"GUIDED_INSTALL_FAILED","errorMessage":"GUIDED_INSTALL_FAILED: ${sanitizeTerminalText(error.message)}","messagePattern":"GUIDED_INSTALL_FAILED: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/install-guided.js","lineNumber":324,"sourceCode":"    } finally {\n      spinner?.stop();\n    }\n    if (options.json) {\n      output.write(`${JSON.stringify({ dryRun: false, result }, null, 2)}\\n`);\n    } else if (result.status === 'complete') {\n      output.write(`\\nECC configured for ${result.completed.map(item => getHarnessCapability(item.id).label).join(', ')}.\\n`);\n      renderWelcome({ action: 'installed', interactive, json: false, output });\n    } else {\n      const retry = buildRetryArguments(plan, result.retryHarnesses);\n      errorOutput.write(\n        `ECC stopped at ${sanitizeTerminalText(result.failure.id)}: `\n        + `${sanitizeTerminalText(result.failure.message)}\\n`\n        + `Retry with: ecc-universal install --guided ${retry}\\n`\n      );\n    }\n    return result.status === 'complete' ? 0 : 1;\n  } catch (error) {\n    const payload = { error: { code: 'GUIDED_INSTALL_FAILED', message: error.message } };\n    if (argv.includes('--json')) errorOutput.write(`${JSON.stringify(payload, null, 2)}\\n`);\n    else errorOutput.write(`Error: ${sanitizeTerminalText(error.message)}\\n`);\n    return 1;\n  } finally {\n    if (ownsTerminal) terminal?.close();\n  }\n}\n\nif (require.main === module) {\n  main().then(code => {\n    process.exitCode = code;\n  });\n}\n\nmodule.exports = {\n  collectInteractiveOptions,\n  main,\n  parseArgs,","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/install-guided.js#L306-L342","documentation":"The guided installer's main() wraps its whole run in a try/catch; any uncaught failure during the guided install flow is normalized to a GUIDED_INSTALL_FAILED payload — written as JSON when --json is set, otherwise a sanitized 'Error: ...' line — and the process exits 1. It is the top-level catch-all for the guided mode.","triggerScenarios":"Any exception thrown inside the guided flow: a step result with status 'failed' and a failure message, a terminal/TTY setup error, invalid CLI flags like an unknown --guided retry token, or unexpected internal exceptions.","commonSituations":"Running ecc-universal install --guided in a non-interactive shell where the terminal controller cannot start; a guided step failing validation and being surfaced through the retry path; a bug/typo in an answer to a guided prompt; piping output in a way that breaks interactive prompts.","solutions":["Read the printed failure message and the suggested 'Retry with: ecc-universal install --guided <retry>' command, and re-run exactly that","Run with --json to get a machine-readable payload for the underlying error message","Run in a real interactive TTY (not a piped/non-interactive shell) if the failure mentions terminal setup","Fall back to non-guided install (ecc-universal install) if guided mode keeps failing"],"exampleFix":"// before\n$ ecc-universal install --guided < /dev/null\nError: terminal unavailable\n\n// after\n$ ecc-universal install --guided   # run interactively, or:\n$ ecc-universal install            # non-guided fallback","handlingStrategy":"retry","validationCode":"if (!process.stdout.isTTY && process.argv.includes('--guided')) {\n  console.error('guided mode needs an interactive terminal'); process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"const code = spawnSync('ecc-universal', ['install', '--guided'], { stdio: 'inherit' });\nif (code.status !== 0) { /* parse stderr for the suggested 'Retry with: ecc-universal install --guided <retry>' command */ }","preventionTips":["Run guided installs only in interactive TTY sessions","Preserve and reuse the retry token printed by a failed run","Prefer the non-guided installer in CI or scripted environments"],"tags":["cli","installer","guided-setup"],"backgroundTag":"guided-install-failed","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}