chenglou/pretext · error · Error

Corpus page returned error for ${meta.id} (${variant.id}): $

Error message

Corpus page returned error for ${meta.id} (${variant.id}): ${report.message ?? 'unknown error'}

What it means

Thrown inside the per-variant sweep loop of corpus-font-matrix.ts after a POSTed report arrives with `status: 'error'`. The page-side harness ran, surfaced a structured error (report.message, else 'unknown error'), and the host rethrows it attributed to the corpus and font variant. This is the page explicitly saying "I could not measure this corpus under this font" — distinct from a timeout ([24]) where the page never answered.

Source

Thrown at scripts/corpus-font-matrix.ts:484

      `&lineHeight=${variant.lineHeight}` +
      `&reportEndpoint=${encodeURIComponent(reportServer.endpoint)}`

    const report = await (async () => {
      try {
        return await loadPostedReport(
          session,
          url,
          () => reportServer.waitForReport(null),
          requestId,
          options.browser,
          options.timeoutMs,
        )
      } finally {
        reportServer.close()
      }
    })()
    if (report.status === 'error') {
      throw new Error(`Corpus page returned error for ${meta.id} (${variant.id}): ${report.message ?? 'unknown error'}`)
    }
    if (report.rows === undefined) {
      throw new Error(`Corpus font matrix report was missing rows for ${meta.id} (${variant.id})`)
    }

    const mismatches: VariantResult['mismatches'] = report.rows
      .filter(row => Math.round(row.diffPx) !== 0)
      .map(row => ({
        width: row.width,
        diffPx: Math.round(row.diffPx),
        predictedHeight: Math.round(row.predictedHeight),
        actualHeight: Math.round(row.actualHeight),
      }))
    const exactCount = report.exactCount ?? (report.rows.length - mismatches.length)

    variantResults.push({
      id: variant.id,
      label: variant.label,

View on GitHub (pinned to ac49b09b7d)

Solutions

Read report.message in the error text — the page intentionally surfaces a cause string, and 'unknown error' means the page caught something it did not classify.
Verify the variant's font string is resolvable on this OS/browsers: open the corpus page in a headed run of the same browser and check the applied font in devtools.
For CJK corpora, confirm the required font families (Hiragino Mincho ProN, Yu Mincho, Noto Serif CJK JP, etc.) are installed — macOS vs Linux font sets differ sharply.
Cross-check the same corpus under the default variant to isolate whether the error is corpus-specific or font-specific.
If the message is generic, add richer error context in the page-side measurement code so future failures self-explain.

Example fix

// before
if (report.status === 'error') {
  throw new Error(`Corpus page returned error for ${meta.id} (${variant.id}): ${report.message ?? 'unknown error'}`)
}
// after — attribute the font so the cause is obvious without re-reading variant config
if (report.status === 'error') {
  throw new Error(`Corpus page error for ${meta.id} (${variant.id}, font=${variant.font}): ${report.message ?? 'unknown error'}`)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight that the variant's font is resolvable before sweeping
async function canResolveFont(font: string): Promise<boolean> {
  // crude: ensure the families referenced are not obviously absent on this OS
  // (full check belongs in the headed browser, but this catches typos)
  return /\d+px\s+/.test(font) // must start with a size; deeper checks need the browser
}

Type guard

function isErrorReport(report: { status?: string }): report is { status: 'error'; message?: string } {
  return report.status === 'error'
}

Try / catch

try {
  report = await loadPostedReport(session, url, () => reportServer.waitForReport(null), requestId, options.browser, options.timeoutMs)
} catch (error) {
  if (error instanceof Error && error.message.startsWith('Corpus page returned error')) {
    // Page-reported error — isolate by re-running the same corpus under the default variant in a headed browser
    console.error(`${error.message}. Reproduce headed: open ${url} in ${options.browser} and watch the console.`)
  }
  throw error
}
if (isErrorReport(report)) {
  throw new Error(`Corpus page error for ${meta.id} (${variant.id}, font=${variant.font}): ${report.message ?? 'unknown error'}`)
}

Prevention

Confirm the variant font families are installed on the host OS, especially CJK families for ja/zh corpora.
Reproduce the failing variant in a headed browser (open the same URL) — the page-side console has the real cause.
Cross-check the same corpus under the default variant to isolate font-specific vs corpus-specific failures.
Enrich the page's error reporter so report.message carries a concrete cause rather than 'unknown error'.

When it happens

Trigger: loadPostedReport resolves with a report object whose `status === 'error'`. The page sets this when: the corpus text failed to load or prepare; the requested font string is invalid or unavailable on the system so canvas measurement fell back badly; a DOM element the page expects (the measure target) was missing; an exception was caught inside the page's measurement loop and reported via the POST channel rather than crashing silently.

Common situations: Font string references a family not installed on the machine (the corpus runs locally, so a missing CJK font is the classic cause); corpus text path changed and the page's loader returned empty; a browser/OS difference (e.g., Safari missing a font Chrome has) makes one variant error while others succeed; the page's error reporter caught a downstream TypeError and forwarded only a generic message.

Related errors

AI-assisted analysis of chenglou/pretext@ac49b09b7d (2026-08-12). Data as JSON: /api/errors/40c8b165f2249035. Report an issue: GitHub.