What causes "SETUP_FAILED: ${error.message}" in affaan-m/ECC?

Read the inner error.message in the SETUP_FAILED payload — it names the real cause (network, permissions, parse failure)

affaan-m/ECC · error

SETUP_FAILED

SETUP_FAILED

Error message

SETUP_FAILED: ${error.message}

What it means

printError in the setup CLI is the last-resort error reporter. When the thrown error is not a ClaudeSetupError (which carries its own code/phase/recovery), it wraps the raw message in a generic SETUP_FAILED payload with phase 'cli' and empty recovery hints (or prints it plainly in non-JSON mode). It signals the setup script aborted for a reason the CLI did not classify.

Solutions

Read the inner error.message in the SETUP_FAILED payload — it names the real cause (network, permissions, parse failure)
Fix the underlying cause (restore network, fix directory permissions, repair/remove the corrupt config) and re-run setup
Run with JSON output to get the structured payload (code, phase, observedScopes) for easier diagnosis
If a specific phase keeps failing, look for a ClaudeSetupError-scoped recovery for that phase in the setup docs

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight checks before setup.js main():
// network reachability, write access to target dirs, existing config JSON.parse

Try / catch

try { runSetup(); } catch (e) {
  const payload = e instanceof ClaudeSetupError ? e.toJSON() : { error: { code: 'SETUP_FAILED', message: e.message } };
  console.error(JSON.stringify(payload));
  // branch on the inner message: network vs permissions vs parse
}

Prevention

Check network and disk-write permissions before running setup
Back up and validate any existing config file the setup script will read or rewrite
Wrap known-failure points in ClaudeSetupError so phase and recovery info survive to printError

When it happens

Trigger: scripts/setup.js throws a plain Error during main() — e.g. failed network fetch of Claude assets, file-system permission errors when writing config, unparseable CLI flags — anything not wrapped as ClaudeSetupError before reaching printError.

Common situations: No network access while setup downloads prerequisites; running setup in a directory without write permissions; corrupted existing config file that setup chokes on; invoking with malformed arguments that skip earlier validation.

Related errors

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

Appendix: source

Thrown at scripts/setup.js:322

    return;
  }
  process.stdout.write(`\nECC ${result.action} ${result.pluginId} at ${result.scope} scope.\n`);
  if (result.sourceScope) {
    process.stdout.write(`Previous scope: ${result.sourceScope}\n`);
  }
  process.stdout.write(`Hook preference: ${result.hooks}\n`);
  if (result.restartRequired) {
    process.stdout.write('Restart Claude Code or run /reload-plugins to load the updated plugin.\n');
  }
}

function printError(error, json) {
  if (json) {
    const payload = error instanceof ClaudeSetupError
      ? error.toJSON()
      : {
        error: {
          code: 'SETUP_FAILED',
          message: error.message,
          phase: 'cli',
          observedScopes: [],
          recovery: [],
        },
      };
    process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
    return;
  }
  process.stderr.write(`Error: ${error.message}\n`);
}

function isInteractiveCancellation(error) {
  return Boolean(error && (
    error.code === 'ABORT_ERR'
    || /aborted with ctrl\+d|readline was closed/i.test(error.message || '')
  ));
}

View on GitHub (pinned to 8321021c54)