What causes "Invalid input: every files entry must contain a non-empty path" in Egonex-AI/Understand-Anything?

Normalize entries to `{ path: " " }` before calling — map bare strings via `p => ({ path: p })`.

Invalid input: every files entry must contain a non-empty pa

Error message

Invalid input: every files entry must contain a non-empty path

What it means

selectAnalysisFiles builds an internal path-keyed map from the `files` argument, requiring every entry to be an object with a non-empty string `path`. A malformed entry (null, a bare string, or an object whose path is empty/undefined) would make the selection map unreliable, so the extractor throws this error immediately.

Source

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

  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,
    // path.isAbsolute also rejects drive-rooted and root-relative paths.
    if (isAbsolute(rawPath)) {
      throw new Error(`Invalid input: analysisPaths entry must be project-relative: ${rawPath}`);
    }
    const path = toPosix(rawPath);
    if (!path || path.split('/').some(part => part === '..')) {

View on GitHub (pinned to 07edf82a04)

Solutions

Normalize entries to `{ path: "<project-relative string>" }` before calling — map bare strings via `p => ({ path: p })`.
Filter falsy entries: `files.filter(Boolean)` and drop entries with empty paths before invocation.
Rename mismatched keys at the boundary: `files.map(f => ({ path: f.filePath ?? f.name }))`.
Validate with `files.every(f => f && typeof f.path === 'string' && f.path.length > 0)` in the producer.

Example fix

// before
selectAnalysisFiles(["src/a.ts", null], analysisPaths);

// after
selectAnalysisFiles([{ path: "src/a.ts" }].filter(f => f && f.path), analysisPaths);

Defensive patterns

Strategy: validation

Validate before calling

const validFiles = files
  .filter(Boolean)
  .map(f => (typeof f === 'string' ? { path: f } : f))
  .filter(f => typeof f.path === 'string' && f.path.length > 0);

Type guard

function isFileEntry(f) {
  return typeof f === 'object' && f !== null && typeof f.path === 'string' && f.path.length > 0;
}

Try / catch

try {
  selectAnalysisFiles(files, analysisPaths);
} catch (err) {
  if (err.message.includes('every files entry')) {
    console.error('files must be [{ path: string }, ...]; sanitize with filter(Boolean) and string-to-object mapping');
  } else {
    throw err;
  }
}

Prevention

Sanitize the files array at the producer boundary (drop nulls, map bare strings to { path }).
Standardize on the `{ path }` field name across all pipeline file records.
Never emit entries for globs that resolved to nothing — skip instead of pushing null.
Validate the array once after discovery, before any consumer runs.

When it happens

Trigger: Calling selectAnalysisFiles with a `files` array containing null/undefined elements, plain string paths instead of `{ path: string }` objects, or entries where `path` is empty string after an upstream filter; also when a files producer emits `{file: ...}` instead of `{path: ...}`.

Common situations: An upstream discovery script maps paths to objects but one glob resolves to nothing and nulls leak in; a caller reuses a different module's file record shape (`{ name }` or `{ filePath }`); empty-string paths from filtering out non-project files without removing the entry.

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/1d3ff6d67ac94cdb. Report an issue: GitHub.