{"record":{"id":"825edbd1c2a30d98","repo":"affaan-m/ECC","slug":"fail-codexpluginsetuperror-with-code-message-and-details","errorCode":null,"errorMessage":"(fail) CodexPluginSetupError with code, message and details","messagePattern":"\\(fail\\) CodexPluginSetupError with code, message and details","errorType":"exception","errorClass":"CodexPluginSetupError","httpStatus":null,"severity":"error","filePath":"scripts/lib/codex-plugin-setup.js","lineNumber":25,"sourceCode":"const CODEX_PLUGIN_ID = 'ecc@ecc';\nconst OFFICIAL_MARKETPLACE_NAME = 'ecc';\nconst OFFICIAL_MARKETPLACE_REPO = 'affaan-m/ECC';\nconst NORMALIZED_OFFICIAL_MARKETPLACE_REPO = OFFICIAL_MARKETPLACE_REPO.toLowerCase();\nconst MAX_OUTPUT_BYTES = 10 * 1024 * 1024;\nconst PROVIDER_COMMAND_TIMEOUT_MS = 120 * 1000;\n\nclass CodexPluginSetupError extends Error {\n  constructor(code, message, details = {}) {\n    super(message);\n    this.name = 'CodexPluginSetupError';\n    this.code = code;\n    this.phase = details.phase || 'inventory';\n    this.argv = [...(details.argv || [])];\n  }\n}\n\nfunction fail(code, message, details) {\n  throw new CodexPluginSetupError(code, message, details);\n}\n\nfunction parseJsonObject(stdout, inventoryName, phase = 'inventory') {\n  let parsed;\n  try {\n    parsed = JSON.parse(String(stdout || ''));\n  } catch (error) {\n    fail(\n      `INVALID_${inventoryName.toUpperCase()}_INVENTORY`,\n      `Codex ${inventoryName} inventory returned invalid JSON: ${error.message}`,\n      { phase }\n    );\n  }\n  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    fail(\n      `INVALID_${inventoryName.toUpperCase()}_INVENTORY`,\n      `Codex ${inventoryName} inventory is invalid: expected a JSON object`,\n      { phase }","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/codex-plugin-setup.js#L7-L43","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\ntry { await setup(); } catch (e) { console.error(e.message); }\n// after\ntry { await setup(); } catch (e) {\n  if (e instanceof CodexPluginSetupError) console.error(e.code, e.phase, e.argv);\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"const which = require('child_process').spawnSync('codex', ['--version']);\nif (which.error || which.status !== 0) throw new Error('codex CLI unavailable');","typeGuard":"function isSetupError(e) { return e && e.name === 'CodexPluginSetupError' && typeof e.code === 'string'; }","tryCatchPattern":"try { await runSetup(); } catch (e) {\n  if (isSetupError(e)) {\n    console.error(`codex setup failed [${e.code}] in phase ${e.phase}: ${e.message}`);\n    // optionally re-run e.argv to inspect raw output\n  } else throw e;\n}","preventionTips":["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"],"tags":["plugins","codex","inventory"],"backgroundTag":"unexpected-api-response-shape","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"}