affaan-m/ECC · error · Error

Invalid ECC version

Error message

Invalid ECC version: ${installedVersion}

What it means

renderTerminalWelcome renders the CLI welcome banner and validates that the version string matches ECC_VERSION_PATTERN before printing. It throws when options.version (or the fallback ECC_VERSION) does not look like a valid ECC version string. This prevents displaying a corrupted or missing version in the terminal UI.

Solutions

1. Pass a version string matching the ECC pattern (e.g. '2.2.1') in options.version.
2. Omit options.version so the built-in ECC_VERSION constant is used.
3. Strip prefixes/suffixes (like a leading 'v' or build metadata) from the version before passing it.
4. Verify where options.version originates (package.json, env) and fix the upstream producer.

Example fix

// before
renderTerminalWelcome({ version: 'v2.2.1' });
// after
renderTerminalWelcome({ version: '2.2.1' });

const ECC_VERSION_PATTERN = /^\d+\.\d+\.\d+.*$/; // mirror of library pattern
if (!ECC_VERSION_PATTERN.test(version)) throw new Error(`Bad version: ${version}`);

const isValidVersion = (v) => typeof v === 'string' && /^\d+\.\d+\.\d+.*$/.test(v);

try {
  renderTerminalWelcome({ version });
} catch (e) {
  if (String(e.message).startsWith('Invalid ECC version')) {
    console.error(`Version string not accepted: ${version}; using default`);
    renderTerminalWelcome();
  } else throw e;
}

When it happens

Trigger: Calling renderTerminalWelcome({ version: 'abc' }) or showTerminalWelcome({ version: '' }); passing a semver with an unexpected format (e.g. a leading 'v' or build metadata the pattern disallows); calling main/welcome with a version sourced from an unparsed file.

Common situations: Piping an env var or build artifact into version; a fork/patched build whose version string deviates from the official pattern; JSON output accidentally passed instead of a plain string.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• all overlays must be readable local files
• all takes must be readable local files
• Arguments must not contain NUL bytes.
• asset name must be a simple filename stem (letters, digits…
• At least one guided harness must be selected

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

Appendix: source

Thrown at scripts/lib/terminal-welcome.js:98

    `Discord:       ${COMMUNITY_LINKS.discord}`,
    `Documentation: ${COMMUNITY_LINKS.documentation}`,
    `GitHub App:     ${COMMUNITY_LINKS.githubApp}`,
  ]);
  const contentWidth = Math.max(...rows.map(row => row.length));
  const border = '─'.repeat(contentWidth + 2);

  return [
    `  ╭${border}╮`,
    ...rows.map(row => `  │ ${row.padEnd(contentWidth)} │`),
    `  ╰${border}╯`,
  ];
}

function renderTerminalWelcome(options = {}) {
  const color = options.color === true;
  const installedVersion = options.version || ECC_VERSION;
  if (!ECC_VERSION_PATTERN.test(installedVersion)) {
    throw new Error(`Invalid ECC version: ${installedVersion}`);
  }
  const graphic = renderWordmark(color);
  const successMessage = SUCCESS_MESSAGES[options.action] || SUCCESS_MESSAGES.installed;
  const welcomeMessage = colorize(successMessage, '1;35', color);
  const version = colorize(`v${installedVersion}`, '2', color);
  const versionLine = color ? `\x1b[1G  ${version}` : `  ${version}`;

  return [
    '',
    graphic,
    '',
    `  ${welcomeMessage}`,
    versionLine,
    '',
    ...renderCommunityLinks(),
    '',
  ].join('\n');
}

View on GitHub (pinned to 8321021c54)