What causes "Markdown report path must be outside the subject repository" in Egonex-AI/Understand-Anything?

Move the output path fully outside the repository so both the JSON and its Markdown sibling are external.

Egonex-AI/Understand-Anything · error · CliUsageError

Markdown report path must be outside the subject repository

Error message

Markdown report path must be outside the subject repository

What it means

CliUsageError thrown by parseArgs when the derived Markdown report path is inside (or equal to) the subject repository. The markdown path is computed from the JSON output path by swapping/adding a .md extension, so an output path inside the repo also drags the markdown path inside it; this guard catches the markdown path specifically (e.g. when the JSON path is just outside but the computed .md lands inside, or as a paired safety check).

Source

Thrown at scripts/lib/large-repo-benchmark.mjs:274

  if (!existsSync(repoRoot)) {
    throw new CliUsageError(`Repository path does not exist: ${repoValue}`);
  }
  if (!statSync(repoRoot).isDirectory()) {
    throw new CliUsageError(`Repository path is not a directory: ${repoValue}`);
  }

  const outputPath = resolve(cwd, outputValue);
  const markdownPath = resolve(
    cwd,
    outputPath.toLowerCase().endsWith('.json')
      ? `${outputPath.slice(0, -'.json'.length)}.md`
      : `${outputPath}.md`,
  );
  if (isPathInsideOrEqual(repoRoot, outputPath)) {
    throw new CliUsageError('--output must be outside the subject repository');
  }
  if (isPathInsideOrEqual(repoRoot, markdownPath)) {
    throw new CliUsageError('Markdown report path must be outside the subject repository');
  }

  return {
    help: false,
    repoRoot,
    outputPath,
    markdownPath,
    label: label || basename(repoRoot),
    concurrency,
    keepArtifacts,
  };
}

export function helpText() {
  return `Usage:
  node scripts/benchmark-large-repo.mjs <repo-path> --output <path> [options]
  node scripts/benchmark-large-repo.mjs --repo <repo-path> --output <path> [options]

View on GitHub (pinned to 32944829e7)

Solutions

Move the output path fully outside the repository so both the JSON and its Markdown sibling are external.
Use an absolute path in a separate reports directory.
Confirm both the JSON and Markdown targets are outside repoRoot before running.
Run with --help to recall the external-artifacts requirement.

Example fix

# before
node benchmark-large-repo.mjs myrepo --output myrepo-report.json
# after
node benchmark-large-repo.mjs myrepo --output ../reports/out.json

Defensive patterns

Strategy: validation

Validate before calling

import { isPathInsideOrEqual } from './lib/large-repo-benchmark.mjs';
const md = outputPath.toLowerCase().endsWith('.json')
  ? outputPath.slice(0, -'.json'.length) + '.md'
  : outputPath + '.md';
if (isPathInsideOrEqual(repoRoot, resolve(cwd, md))) { /* move output outside repo */ }

Try / catch

try { const opts = parseArgs(argv); } catch (e) { if ((e as Error).name === 'CliUsageError') { console.error(e.message); process.exit(2); } throw e; }

Prevention

Place both JSON and Markdown reports in an external reports directory.
Pick output paths whose .md sibling also resolves outside the repo.

When it happens

Trigger: An --output path whose computed .md variant resolves inside repoRoot; typically paired with error 17 but can fire independently when the .json/.md extension swap changes directory membership in an edge case.

Common situations: Output path placed at the repo boundary such that the markdown sibling lands inside; naming the output with a non-.json extension so the .md is appended and lands inside the repo.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@32944829e7 (2026-08-12). Data as JSON: /api/errors/1fb5bb1c19fd9ff9. Report an issue: GitHub.