affaan-m/ECC · error

Invalid ECC version: ${installedVersion}

Error message

Invalid ECC version: ${installedVersion}

What it means

Thrown by renderTerminalWelcome() when the supplied or package-derived ECC version does not match ECC_VERSION_PATTERN, a strict semver regex (MAJOR.MINOR.PATCH with optional prerelease and build metadata). The function builds an ANSI-colored banner that includes the version literal, so a malformed value would corrupt the layout or mislead the user. The check runs before any rendering work.

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 01e15490f0)

Solutions

1. Use a strict semver string: '2.2.0', '2.2.0-beta.1', '2.2.0+build.4'.
2. Strip a leading 'v' before passing the value: version.replace(/^v/, '').
3. If you cannot guarantee semver, omit options.version — the function falls back to ECC_VERSION from package.json, which the maintainers keep semver-compliant.
4. In a fork, either keep package.json semver-compliant or validate and rewrite the version before calling renderTerminalWelcome.

Example fix

// before
showTerminalWelcome({ version: 'v2.2.0' });   // leading v fails the regex

// after
showTerminalWelcome({ version: '2.2.0' });
// or omit version entirely to use package.json ECC_VERSION

const SEMVER = /^[0-9]+(?:\.[0-9]+){2}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;

function safeVersion(raw) {
  const v = typeof raw === 'string' ? raw.replace(/^v/i, '') : raw;
  if (typeof v === 'string' && SEMVER.test(v)) return v;
  return null;  // or fall back to package.json ECC_VERSION
}

const version = safeVersion(process.env.ECC_VERSION);
showTerminalWelcome(version ? { version } : {});

const ECC_VERSION_PATTERN = /^[0-9]+(?:\.[0-9]+){2}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;

function isSemver(value) {
  return typeof value === 'string' && ECC_VERSION_PATTERN.test(value);
}

try {
  showTerminalWelcome({ version });
} catch (error) {
  if (/Invalid ECC version/.test(error.message)) {
    // fall back to the package.json version
    showTerminalWelcome({});
    return;
  }
  throw error;
}

When it happens

Trigger: Passing options.version = 'latest', '2.2', 'v2.2.0', '2.2.0-dev', or '' explicitly; a package.json that has been mutated to a non-semver version (e.g. a git describe tag like '2.2.0-14-gabc1234' is allowed only if it matches the prerelease shape); a downstream distribution that rewrote package.json version to a placeholder.

Common situations: CI sets package.version to a commit SHA; a fork changes the version scheme; options.version is read from an env var with a typo; a prerelease tag contains disallowed characters (the regex allows [0-9A-Za-z.-] but not spaces or symbols).

Related errors

• Unsupported memory schema.
• Unsupported canonical session schema version: ${snapshot.sch
• skillPath is required
• ECC_PROJECT_DIR must be a child path within /workspace.
• Unknown argument: ${arg}

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/f414d0aec73cc2f0. Report an issue: GitHub.