koala73/worldmonitor · error · Error

${stale.map((output) => output.relativePath).join(' and ')}

Error message

${stale.map((output) => output.relativePath).join(' and ')} stale — run npm run build:llms-full

What it means

writeLlmsFull with check=true (CI/check mode) regenerates all output files and compares them to what is on disk. If any generated output differs from the committed file, it throws listing the stale relative paths, telling you to run npm run build:llms-full. It prevents shipping docs that do not match the generator.

Solutions

Run npm run build:llms-full to regenerate and rewrite the stale files.
Commit the regenerated outputs to the branch.
Avoid hand-editing generated files; change the generator or its inputs instead.
Re-run the check command to confirm it passes before pushing.

Example fix

// before
# public/llms.txt hand-edited, generator output differs
// after
npm run build:llms-full && git add public/llms.txt && git commit

Defensive patterns

Strategy: validation

Validate before calling

const next = buildLlmsFullText();
if (next !== readFileSync('public/llms.txt', 'utf8')) throw new Error('llms.txt stale — run npm run build:llms-full');

Try / catch

try { writeLlmsFull({ check: true }); } catch (e) { console.error(e.message); process.exit(1); }

Prevention

Always run npm run build:llms-full after touching llms outputs or the generator.
Commit regenerated artifacts in the same PR as generator changes.
Never hand-edit generated files.

When it happens

Trigger: Running the build in check mode (e.g. npm run build:llms-full -- --check in CI) after llms.txt or related outputs were edited manually, or after generator/data changes without re-running the build to refresh the outputs.

Common situations: Hand-editing public/llms.txt without regenerating; a PR updated generator logic or OpenAPI bytes but forgot to commit regenerated files; CI runs check mode on a branch with stale committed artifacts.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

/**
 * Writes both agent files: the Comparisons section spliced into llms.txt and
 * the full corpus. One script owns both so the section cannot drift between
 * them (#7746). Both outputs are rendered before anything is written or
 * judged, so --check names every stale file at once and a render failure
 * never leaves the pair half-written. Returns one entry per file.
 */
export function writeLlmsFull({ rootDir = ROOT, check = false } = {}) {
  const outputs = [
    { relativePath: LLMS_TXT_PATH, next: withComparisonsSection(read(rootDir, LLMS_TXT_PATH)) },
    { relativePath: OUTPUT_PATH, next: buildLlmsFullText({ rootDir }) },
  ].map(({ relativePath, next }) => {
    const path = join(rootDir, relativePath);
    const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
    return { path, relativePath, next, changed: current !== next, bytes: Buffer.byteLength(next) };
  });
  const stale = outputs.filter((output) => output.changed);
  if (check && stale.length > 0) {
    throw new Error(`${stale.map((output) => output.relativePath).join(' and ')} stale — run npm run build:llms-full`);
  }
  for (const output of stale) writeFileSync(output.path, output.next);
  return { files: outputs.map(({ relativePath, changed, bytes }) => ({ path: relativePath, changed, bytes })) };
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const check = process.argv.includes('--check');
  try {
    const result = writeLlmsFull({ check });
    for (const file of result.files) {
      const kb = (file.bytes / 1000).toFixed(1);
      process.stdout.write(
        `${file.changed ? 'Wrote' : 'Unchanged'} ${file.path} (${kb} KB)\n`,
      );
    }
  } catch (err) {
    process.stderr.write(`${err.stack || err.message}\n`);
    process.exit(1);

View on GitHub (pinned to 7d06c8633d)