affaan-m/ECC · error · Error

Invalid ${flag}: expected a single cache path segment

Error message

Invalid ${flag}: expected a single cache path segment

What it means

The validateCacheSegment() function in check-plugin-cache.js enforces that --marketplace, --plugin, and --version values are single path segments with no directory traversal. It rejects empty strings, null bytes, '..', '/', '\', and absolute paths on both POSIX and Windows. This is a security guard preventing path traversal attacks on the Codex plugin cache directory, which is constructed via path.join(codexHome, 'plugins', 'cache', marketplace, plugin, version).

Source

Thrown at scripts/codex/check-plugin-cache.js:41

    '  --marketplace <name> Marketplace cache name (default: ecc)',
    '  --plugin <name>      Plugin cache name (default: ecc)',
    '  --version <version>  Plugin version (default: package.json version)',
    '  --help              Show this help text',
  ].join('\n'));
}

function validateCacheSegment(flag, value) {
  if (
    typeof value !== 'string' ||
    value.trim() === '' ||
    value.includes('\0') ||
    value.includes('..') ||
    value.includes('/') ||
    value.includes('\\') ||
    path.isAbsolute(value) ||
    path.win32.isAbsolute(value)
  ) {
    throw new Error(`Invalid ${flag}: expected a single cache path segment`);
  }
  return value;
}

function parseArgs(argv) {
  const defaults = {
    marketplace: 'ecc',
    plugin: 'ecc',
    version: PACKAGE_JSON.version,
    codexHome: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
    pluginDir: null,
  };
  const optionKeys = {
    '--codex-home': 'codexHome',
    '--plugin-dir': 'pluginDir',
    '--marketplace': 'marketplace',
    '--plugin': 'plugin',
    '--version': 'version',

View on GitHub (pinned to 01e15490f0)

Solutions

1. Use simple alphanumeric or hyphenated names for --marketplace and --plugin (e.g. 'ecc')
2. For --version, use the exact version string from package.json (e.g. '2.2.0') without path separators
3. If you need to check a specific directory, use --plugin-dir with an absolute path instead of manipulating --marketplace/--plugin/--version

Example fix

// before
node scripts/codex/check-plugin-cache.js --marketplace ../custom --plugin my/plugin
// after
node scripts/codex/check-plugin-cache.js --marketplace ecc --plugin ecc
// or point directly:
node scripts/codex/check-plugin-cache.js --plugin-dir /abs/path/to/cache

// Validate cache segment values before passing them as CLI arguments
function isValidCacheSegment(value) {
  return typeof value === 'string'
    && value.trim() !== ''
    && !value.includes('\0')
    && !value.includes('..')
    && !value.includes('/')
    && !value.includes('\\')
    && !require('path').isAbsolute(value)
    && !require('path').win32.isAbsolute(value);
}

const marketplace = process.env.PLUGIN_MARKETPLACE || 'ecc';
if (!isValidCacheSegment(marketplace)) {
  throw new Error(`Invalid marketplace segment: ${marketplace}`);
}

// Type guard for a safe cache path segment
function isSafeCacheSegment(value) {
  return typeof value === 'string'
    && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(value);
}

try {
  const options = parseArgs(process.argv.slice(2));
} catch (error) {
  if (error.message.includes('expected a single cache path segment')) {
    console.error('Cache segment values must be simple names without path separators or traversal.');
    console.error('Use --plugin-dir <abs-path> to check a specific directory instead.');
    process.exit(2);
  }
  throw error;
}

When it happens

Trigger: Passing --marketplace '../etc', --plugin 'foo/bar', --version '1.0/../../', or any value containing backslashes, forward slashes, dot-dot, null bytes, or that is empty. Also triggered when an environment variable feeding these values contains unexpected characters.

Common situations: Attempting to point the cache checker at a plugin nested outside the cache root; shell scripts that interpolate user-controlled paths into --marketplace or --plugin; Windows users whose values inadvertently contain backslash path separators.

Related errors

• Unknown argument: ${arg}
• Missing value for ${arg}
• TypeScript compiler not found. Install root dev dependencies
• ${source} is missing the expected catalog marker
• Unknown argument: ${arg}

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