GUIDED_INSTALL_FAILED

GUIDED_INSTALL_FAILED

Error message

GUIDED_INSTALL_FAILED: ${sanitizeTerminalText(error.message)}

What it means

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.

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

Example fix

// before
$ ecc-universal install --guided < /dev/null
Error: terminal unavailable

// after
$ ecc-universal install --guided   # run interactively, or:
$ ecc-universal install            # non-guided fallback

Defensive patterns

Strategy: retry

Validate before calling

if (!process.stdout.isTTY && process.argv.includes('--guided')) {
  console.error('guided mode needs an interactive terminal'); process.exit(1);
}

Try / catch

const code = spawnSync('ecc-universal', ['install', '--guided'], { stdio: 'inherit' });
if (code.status !== 0) { /* parse stderr for the suggested 'Retry with: ecc-universal install --guided <retry>' command */ }

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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

Appendix: source

Thrown at scripts/install-guided.js:324

    } finally {
      spinner?.stop();
    }
    if (options.json) {
      output.write(`${JSON.stringify({ dryRun: false, result }, null, 2)}\n`);
    } else if (result.status === 'complete') {
      output.write(`\nECC configured for ${result.completed.map(item => getHarnessCapability(item.id).label).join(', ')}.\n`);
      renderWelcome({ action: 'installed', interactive, json: false, output });
    } else {
      const retry = buildRetryArguments(plan, result.retryHarnesses);
      errorOutput.write(
        `ECC stopped at ${sanitizeTerminalText(result.failure.id)}: `
        + `${sanitizeTerminalText(result.failure.message)}\n`
        + `Retry with: ecc-universal install --guided ${retry}\n`
      );
    }
    return result.status === 'complete' ? 0 : 1;
  } catch (error) {
    const payload = { error: { code: 'GUIDED_INSTALL_FAILED', message: error.message } };
    if (argv.includes('--json')) errorOutput.write(`${JSON.stringify(payload, null, 2)}\n`);
    else errorOutput.write(`Error: ${sanitizeTerminalText(error.message)}\n`);
    return 1;
  } finally {
    if (ownsTerminal) terminal?.close();
  }
}

if (require.main === module) {
  main().then(code => {
    process.exitCode = code;
  });
}

module.exports = {
  collectInteractiveOptions,
  main,
  parseArgs,

View on GitHub (pinned to 8321021c54)