tinyhumansai/openhuman · error · Error

generated-block markers not found in ${FRONTEND_DOC}; expect

Error message

generated-block markers not found in ${FRONTEND_DOC}; expected HTML comments containing "${BLOCK_BEGIN_TOKEN}" and "${BLOCK_END_TOKEN}"

What it means

Thrown by spliceGeneratedBlock() when gitbooks/developing/architecture/frontend.md has no line containing the literal tokens 'BEGIN GENERATED: provider-chain' / 'END GENERATED: provider-chain' (inside HTML comments). The generator replaces only the content between those comments; if either marker line is gone it cannot splice and refuses to rewrite the whole doc.

Source

Thrown at scripts/generate-architecture-docs.mjs:120

    '',
  ];
}

/**
 * Splice freshly rendered body lines into `docSource` between the BEGIN/END
 * marker lines (markers preserved). Returns the updated document text.
 *
 * @param {string} docSource
 * @param {string[]} bodyLines
 * @returns {string}
 * @throws if the markers are missing or out of order
 */
export function spliceGeneratedBlock(docSource, bodyLines) {
  const lines = docSource.split('\n');
  const beginIdx = lines.findIndex(l => l.includes(BLOCK_BEGIN_TOKEN));
  const endIdx = lines.findIndex(l => l.includes(BLOCK_END_TOKEN));
  if (beginIdx === -1 || endIdx === -1) {
    throw new Error(
      `generated-block markers not found in ${FRONTEND_DOC}; expected HTML comments ` +
        `containing "${BLOCK_BEGIN_TOKEN}" and "${BLOCK_END_TOKEN}"`
    );
  }
  if (endIdx <= beginIdx) {
    throw new Error('generated-block END marker must come after the BEGIN marker');
  }
  const next = [...lines.slice(0, beginIdx + 1), ...bodyLines, ...lines.slice(endIdx)];
  return next.join('\n');
}

/**
 * Compute the desired doc content from the current sources.
 * @returns {{ updated: string, current: string }}
 */
export function computeFrontendDoc() {
  const providers = parseProviderChain(readFileSync(APP_TSX, 'utf8'));
  const current = readFileSync(FRONTEND_DOC, 'utf8');

View on GitHub (pinned to a221052e0d)

Solutions

Restore the two HTML comment markers in gitbooks/developing/architecture/frontend.md, e.g. `git checkout HEAD -- gitbooks/developing/architecture/frontend.md` or copy them from git history
If the section was intentionally relocated, wrap the table in the new location with `` and `` exactly (token text is matched by substring)
Re-run `node scripts/generate-architecture-docs.mjs` and verify only the region between markers changed

Example fix

<!-- before — markers stripped from frontend.md -->
| # | Component | Role |
|---|-----------|------|

<!-- after — markers restored around the generated table -->
<!-- BEGIN GENERATED: provider-chain -->
| # | Component | Role |
|---|-----------|------|
<!-- END GENERATED: provider-chain -->

Defensive patterns

Strategy: validation

Validate before calling

const doc = readFileSync('gitbooks/developing/architecture/frontend.md', 'utf8');
const hasBegin = doc.includes('BEGIN GENERATED: provider-chain');
const hasEnd = doc.includes('END GENERATED: provider-chain');
if (!hasBegin || !hasEnd) {
  console.error(`frontend.md marker check: BEGIN=${hasBegin} END=${hasEnd} — restore the HTML comment markers`);
  process.exit(1);
}

Try / catch

try {
  spliceGeneratedBlock(docSource, bodyLines);
} catch (err) {
  if (err.message.includes('generated-block markers not found')) {
    console.error('frontend.md lost its <!-- BEGIN/END GENERATED: provider-chain --> comments — restore from git');
    process.exitCode = 1;
  } else throw err;
}

Prevention

Never hand-edit or delete the BEGIN/END GENERATED HTML comments when touching frontend.md — only content between them is regenerated
If the section must move, move the marker pair with the table in the same commit and run `pnpm docs:check`
Protect the markers in review: any diff deleting `<!-- BEGIN GENERATED` / `<!-- END GENERATED` lines deserves a hard look

When it happens

Trigger: Running `pnpm docs:generate` or `--check` after the generated block in frontend.md — including its `` / `` comment lines — was deleted, or the doc file was recreated/renamed so FRONTEND_DOC resolves to a file without markers.

Common situations: Someone 'tidying' the doc removes what looks like stray HTML comments; a docs restructure moves the provider-chain section to a new file without carrying the marker comments; a merge conflict resolution drops the marker lines.

Related errors

AI-assisted analysis of tinyhumansai/openhuman@a221052e0d (2026-08-16). Data as JSON: /api/errors/4c9592e4532bfc1d. Report an issue: GitHub.