itwanger/toBeBetterJavaer · error · Error

--route and --dir must be used together

Error message

--route and --dir must be used together

What it means

Thrown by parseArgs() in scripts/sync-sidebar.js after the flag loop when exactly one of --route/--dir is provided. The two options form a pair: the route names the sidebar.ts keys entry (normalized to leading and trailing slashes) and the dir names the Markdown directory whose slugs sync into that route's array.

Solutions

1. Supply both: `--route=/sidebar/itwanger/ai/ --dir=docs/src/sidebar/itwanger/ai`
2. Or drop both to sync the built-in default target
3. Note normalizeRoute adds surrounding slashes for you, so `--route sidebar/itwanger/ai` also works

Example fix

# before
node scripts/sync-sidebar.js --dir=docs/src/sidebar/itwanger/ai

# after
node scripts/sync-sidebar.js --route=sidebar/itwanger/ai --dir=docs/src/sidebar/itwanger/ai

const hasRoute = args.some((a) => a === "--route" || a.startsWith("--route="));
const hasDir = args.some((a) => a === "--dir" || a.startsWith("--dir="));
if (hasRoute !== hasDir) throw new Error("Pass both --route and --dir, or neither (defaults are used)");

catch (err) { if (err.message === "--route and --dir must be used together") { console.error("Add the missing half of the pair (see --help)"); process.exit(2); } throw err; }

When it happens

Trigger: `--route=/sidebar/itwanger/ai/` without --dir; `--dir=docs/src/sidebar/itwanger/ai` without --route; a typo'd `--dirs=` lands in the unknown-option branch instead, so this error specifically means one valid member of the pair is present alone.

Common situations: Quick one-off invocations where only the directory is pasted in; copy-pasting half of a documented example command; forgetting that omitting BOTH is valid (falls back to DEFAULT_TARGETS).

Related errors

• Missing value for
• Missing value for
• Unknown option
• Unknown option
• must be a positive integer

AI-assisted analysis of itwanger/toBeBetterJavaer@6617f5fd0b (2026-08-14). Data as JSON: /api/errors/13c5ca9f0558b133. Report an issue: GitHub.

Appendix: source

Thrown at scripts/sync-sidebar.js:86

    } else if (arg.startsWith("--route=")) {
      options.route = normalizeRoute(arg.slice("--route=".length));
    } else if (arg === "--dir") {
      options.dir = requireValue(argv, index);
      index += 1;
    } else if (arg.startsWith("--dir=")) {
      options.dir = arg.slice("--dir=".length);
    } else if (arg === "--fallback") {
      options.fallbackGroup = requireValue(argv, index);
      index += 1;
    } else if (arg.startsWith("--fallback=")) {
      options.fallbackGroup = arg.slice("--fallback=".length);
    } else {
      throw new Error(`Unknown option: ${arg}`);
    }
  }

  if ((options.route && !options.dir) || (!options.route && options.dir)) {
    throw new Error("--route and --dir must be used together");
  }

  return options;
}

function requireValue(argv, index) {
  const value = argv[index + 1];
  if (!value || value.startsWith("-")) {
    throw new Error(`Missing value for ${argv[index]}`);
  }
  return value;
}

function normalizeRoute(route) {
  if (!route.startsWith("/")) {
    route = `/${route}`;
  }
  if (!route.endsWith("/")) {

View on GitHub (pinned to 6617f5fd0b)