What causes "Invalid input: analysisPaths must be an array when provided" in Egonex-AI/Understand-Anything?

Pass an array: `analysisPaths: ["src/a.ts", "src/b.ts"]`, with every entry a non-empty project-relative string.

Invalid input: analysisPaths must be an array when provided

Error message

Invalid input: analysisPaths must be an array when provided

What it means

selectAnalysisFiles in extract-import-map.mjs treats `analysisPaths` as an optional restrictor: when omitted, all discovered files are analyzed. The option is strictly typed, so passing it in any non-array form (string, null, single path) throws this error to prevent accidental full-project scans or silent misreads during incremental extraction.

Source

Thrown at understand-anything-plugin/skills/understand/extract-import-map.mjs:114

/**
 * Normalize a project-relative path to forward slashes (POSIX). Project-scanner
 * always emits forward slashes; we re-normalize to keep this script
 * cross-platform.
 */
function toPosix(p) {
  const separators = process.platform === 'win32' ? /[\\/]/ : /\//;
  return p.split(separators).filter(Boolean).join('/');
}

/**
 * Validate and normalize the optional selective-analysis path list. Keeping
 * this strict prevents an incremental caller from accidentally asking the
 * extractor to read outside projectRoot or silently miss a typo.
 */
function selectAnalysisFiles(files, analysisPaths) {
  if (analysisPaths === undefined) return files;
  if (!Array.isArray(analysisPaths)) {
    throw new Error('Invalid input: analysisPaths must be an array when provided');
  }

  const filesByPath = new Map();
  for (const file of files) {
    if (!file || typeof file.path !== 'string' || file.path.length === 0) {
      throw new Error('Invalid input: every files entry must contain a non-empty path');
    }
    filesByPath.set(toPosix(file.path), file);
  }

  const selected = [];
  const seen = new Set();
  for (const rawPath of analysisPaths) {
    if (typeof rawPath !== 'string' || rawPath.length === 0) {
      throw new Error('Invalid input: every analysisPaths entry must be a non-empty string');
    }
    // Use the host's path semantics here. On POSIX, backslashes and drive-like
    // prefixes are ordinary project-relative filename characters; on Windows,

View on GitHub (pinned to 07edf82a04)

Solutions

Pass an array: `analysisPaths: ["src/a.ts", "src/b.ts"]`, with every entry a non-empty project-relative string.
To analyze everything, omit the `analysisPaths` key entirely — do not pass null.
Split comma-joined CLI values before calling: `value ? value.split(',') : undefined`.
Normalize null to undefined at the config-loading boundary so only arrays or undefined reach the extractor.

Example fix

// before
runImportMap({ files, analysisPaths: "src/a.ts" });

// after
runImportMap({ files, analysisPaths: ["src/a.ts"] }); // or omit key entirely

Defensive patterns

Strategy: type-guard

Validate before calling

if (analysisPaths !== undefined && !Array.isArray(analysisPaths)) {
  throw new TypeError('analysisPaths must be an array of project-relative strings or omitted');
}

Type guard

function isAnalysisPaths(v) {
  return v === undefined || (Array.isArray(v) && v.every(p => typeof p === 'string' && p.length > 0));
}

Try / catch

try {
  selectAnalysisFiles(files, analysisPaths);
} catch (err) {
  if (err.message.includes('analysisPaths must be an array')) {
    console.error('Pass analysisPaths as an array (or omit it for all files), got:', typeof analysisPaths);
  } else {
    throw err;
  }
}

Prevention

Normalize config at load time: `analysisPaths: cfg.analysisPaths == null ? undefined : [].concat(cfg.analysisPaths)`.
Split comma-joined CLI values before invoking the extractor.
Prefer omitting the key over passing null when you want the whole project analyzed.
Document in the caller that the option is array-or-undefined only.

When it happens

Trigger: Calling selectAnalysisFiles (or the extract-import-map entry) with options `{ analysisPaths: "src/a.ts" }` (a bare string), `{ analysisPaths: null }`, or a comma-joined string from CLI parsing, instead of an array of project-relative path strings.

Common situations: A CLI flag parsed with a default of null instead of undefined; a config file that stores analysisPaths as a comma-separated string; a caller intending 'no restriction' passing null rather than omitting the key; a refactor from a single `analysisPath` option to plural.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/c166c34e34b2b072. Report an issue: GitHub.