affaan-m/ECC · error · CodexPluginSetupError

(fail) CodexPluginSetupError with code, message and details

Error message

(fail) CodexPluginSetupError with code, message and details

What it means

fail() is the single throw helper for CodexPluginSetupError in codex-plugin-setup.js. Every inventory parsing, marketplace resolution, and `codex` CLI invocation step funnels failures through it, attaching a machine-readable code, message, phase, and argv to the error. Hitting it means a plugin setup step failed with a structured, diagnosable error.

Solutions

Read error.code, error.phase, and error.argv on the thrown CodexPluginSetupError to identify the failing step
Re-run the codex command from error.argv manually to see its raw output
Fix the underlying cause: reinstall/update the codex CLI, correct the marketplace repository, or repair the plugin inventory files
Re-run setup after correcting the input

Example fix

// before
try { await setup(); } catch (e) { console.error(e.message); }
// after
try { await setup(); } catch (e) {
  if (e instanceof CodexPluginSetupError) console.error(e.code, e.phase, e.argv);
  throw e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

const which = require('child_process').spawnSync('codex', ['--version']);
if (which.error || which.status !== 0) throw new Error('codex CLI unavailable');

Type guard

function isSetupError(e) { return e && e.name === 'CodexPluginSetupError' && typeof e.code === 'string'; }

Try / catch

try { await runSetup(); } catch (e) {
  if (isSetupError(e)) {
    console.error(`codex setup failed [${e.code}] in phase ${e.phase}: ${e.message}`);
    // optionally re-run e.argv to inspect raw output
  } else throw e;
}

Prevention

Keep the codex CLI installed and up to date
Never hand-edit plugin inventory JSON; use the tool
Validate marketplace repository URLs before setup
Log code/phase/argv on failure to speed diagnosis

When it happens

Trigger: Any of the calling functions — parseJsonObject, parseMarketplaceInventory, assertPluginEntries, parsePluginInventory, runCodexCommand, resolveMarketplaceRepository — detect an invalid condition (malformed JSON output, missing marketplace repo, failing codex command, plugin entry violations) and call fail(code, message, details).

Common situations: The `codex` CLI is missing/outdated and emits non-JSON output; a marketplace repository URL is wrong or unreachable; plugin inventory files are hand-edited and violate the expected schema.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at scripts/lib/codex-plugin-setup.js:25

const CODEX_PLUGIN_ID = 'ecc@ecc';
const OFFICIAL_MARKETPLACE_NAME = 'ecc';
const OFFICIAL_MARKETPLACE_REPO = 'affaan-m/ECC';
const NORMALIZED_OFFICIAL_MARKETPLACE_REPO = OFFICIAL_MARKETPLACE_REPO.toLowerCase();
const MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
const PROVIDER_COMMAND_TIMEOUT_MS = 120 * 1000;

class CodexPluginSetupError extends Error {
  constructor(code, message, details = {}) {
    super(message);
    this.name = 'CodexPluginSetupError';
    this.code = code;
    this.phase = details.phase || 'inventory';
    this.argv = [...(details.argv || [])];
  }
}

function fail(code, message, details) {
  throw new CodexPluginSetupError(code, message, details);
}

function parseJsonObject(stdout, inventoryName, phase = 'inventory') {
  let parsed;
  try {
    parsed = JSON.parse(String(stdout || ''));
  } catch (error) {
    fail(
      `INVALID_${inventoryName.toUpperCase()}_INVENTORY`,
      `Codex ${inventoryName} inventory returned invalid JSON: ${error.message}`,
      { phase }
    );
  }
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    fail(
      `INVALID_${inventoryName.toUpperCase()}_INVENTORY`,
      `Codex ${inventoryName} inventory is invalid: expected a JSON object`,
      { phase }

View on GitHub (pinned to 8321021c54)