koala73/worldmonitor · error · Error

${LLMS_TXT_PATH} must carry a "${COMPARISONS_ANCHOR_HEADING}

Error message

${LLMS_TXT_PATH} must carry a "${COMPARISONS_ANCHOR_HEADING}" heading to anchor the Comparisons section

What it means

When llms.txt has no existing '## Comparisons' heading, withComparisonsSection inserts the block before a designated anchor heading (COMPARISONS_ANCHOR_HEADING). If that anchor heading is absent from the document, there is no defined insertion point, so the function throws.

Solutions

1. Add the required anchor heading (the exact COMPARISONS_ANCHOR_HEADING text, on its own line) to llms.txt at the point where Comparisons should precede.
2. Or add the '## Comparisons' section itself via npm run build:llms-full after restoring the standard document structure.
3. Update the generation template so the anchor heading is always emitted before running withComparisonsSection.

Example fix

// before (llms.txt, anchor missing)
## Endpoints
...
// after
## Comparison anchors
...
## Endpoints
...

if (!text.includes(`\n${COMPARISONS_ANCHOR_HEADING}\n`)) throw new Error('anchor heading missing from llms.txt');

try { out = withComparisonsSection(txt); } catch (e) { console.error('Restore anchor heading:', e.message); process.exit(1); }

When it happens

Trigger: Calling withComparisonsSection on llms.txt that lacks both the '## Comparisons' section and the required COMPARISONS_ANCHOR_HEADING heading — e.g. a rewritten or truncated llms.txt that dropped the anchor section.

Common situations: Regenerating llms.txt from scratch with a template that omitted the anchor heading; manual editing removed the section the anchor lived in; upstream doc restructure renamed headings.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• needs a summary for the llms.txt Comparisons section
• ${LLMS_TXT_PATH} carries ${headings.length} "${COMPARISONS_H
• llms.txt must contain exactly one OpenAPI YAML byte-size ann
• is missing methodology prose
• is missing following prose

AI-assisted analysis of koala73/worldmonitor@7d06c8633d (2026-09-15). Data as JSON: /api/errors/a7ec8d0631a7023b. Report an issue: GitHub.

Appendix: source

Thrown at scripts/build-llms-full.mjs:286

 * Live Instances the first time. Idempotent, so --check can diff it.
 */
export function withComparisonsSection(llmsTxt) {
  const text = String(llmsTxt);
  const block = renderComparisons();
  const headings = [...text.matchAll(/^## Comparisons$/gm)];
  if (headings.length > 1) {
    throw new Error(`${LLMS_TXT_PATH} carries ${headings.length} "${COMPARISONS_HEADING}" headings; keep exactly one`);
  }
  if (headings.length === 1) {
    const start = headings[0].index;
    const nextHeading = text.indexOf('\n## ', start + COMPARISONS_HEADING.length);
    const end = nextHeading === -1 ? text.length : nextHeading;
    return `${text.slice(0, start)}${block}\n${text.slice(end)}`;
  }
  const anchor = `\n${COMPARISONS_ANCHOR_HEADING}\n`;
  const at = text.indexOf(anchor);
  if (at === -1) {
    throw new Error(`${LLMS_TXT_PATH} must carry a "${COMPARISONS_ANCHOR_HEADING}" heading to anchor the Comparisons section`);
  }
  return `${text.slice(0, at + 1)}${block}\n${text.slice(at)}`;
}

export function buildLlmsFullText({ rootDir = ROOT } = {}) {
  const existing = existsSync(join(rootDir, OUTPUT_PATH))
    ? read(rootDir, OUTPUT_PATH)
    : '';
  const prefix = withVersionHeader(briefPrefix(existing), readVersionHeader(rootDir));
  const introduction = [
    LLMS_FULL_GENERATED_HEADING,
    '',
    'The sections below are produced by `npm run build:llms-full` from the source catalog, comparison-page registry, glossary terms, chokepoint methodology, published chokepoint explainers, the forecast accuracy snapshot, the Country Resilience Index methodology, the corrections log, and the current published ranking snapshot.',
    '',
    renderSourceDirectory(rootDir),
    '',
    renderComparisons().trim(),
    '',

View on GitHub (pinned to 7d06c8633d)