Skip to content

Add further information to output - #80

Merged
JackLewis-digirati merged 3 commits into
mainfrom
feature/improveErrorMessages
Nov 12, 2026
Merged

JackLewis-digirati merged 3 commits into
mainfrom
feature/improveErrorMessages

Conversation

@JackLewis-digirati

@JackLewis-digirati JackLewis-digirati commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

What does this change?

When a job completes with no words, the only information available today is totalWordCount: 0. Several different causes look identical, and most of them aren't recorded anywhere (dlcs/iiif-presentation#677 is an example of this being hard to diagnose). This PR records why pages produced no text, so callers can tell the user.

Page errors that were previously silent

These are added to errors on a completed job, one line per page, alongside the fetch exceptions that were already recorded there:

  • Text source not found or empty (e.g. a 404). Previously the page was skipped with a Debug log only. Now: {canvasId}: no text found at {textUri}. Applies to ALTO/hOCR, VTT and annotation pages.
  • Unsupported format. TextBuilder.AddPage / AddTranscriptPage now return false when no provider handles the page, instead of only logging a warning. Now: {canvasId}: unsupported text format at {textUri} (profile '…', format '…').

New counts

Three new fields on the job, the job response (GET /textbuilder/{id}) and JobCompletionNotification:

Field Meaning
skippedCanvases Canvases in the source manifest that weren't processed as pages. ManifestReducer.Reduce now returns this alongside the pages, in a new ReducedManifest record. Always 0 for sourceData jobs.
pagesWithoutTextSource Pages with no text source.
pagesWithoutWords Pages whose text source was read but had no words. Uses a new TextBuilder.WordCount.

These aren't errors: a manifest can include a cover or blank page with no OCR, and that shouldn't be reported as a failure. They're reset on reprocess.

Example

A completion notification for a two-canvas manifest where one ALTO file is missing and the other has no words:

{
  "jobId": "1/my-manifest",
  "status": "Completed",
  "finished": "2026-11-05T10:00:00+00:00",
  "totalPages": 2,
  "totalWordCount": 0,
  "errors": "https://example.org/canvases/c1: no text found at https://example.org/alto/c1.xml",
  "invocationCount": 1,
  "skippedCanvases": 0,
  "pagesWithoutTextSource": 0,
  "pagesWithoutWords": 1
}

Behaviour change

Jobs whose text files return 404 (or are empty) now complete with errors set, where previously errors was null. The job status is unchanged (Completed). Anything that treats a non-null errors on a completed job as a failure will see this.

Consumers

  • iiif-presentation is being updated to read the new counts and errors for completed jobs, and to show them as a warning on finishedPipelines.
  • The new notification fields are additive. Consumers that don't know about them can ignore them.

Tests

  • New TextBuilderTests, plus new tests in TextBuildJobTests (missing text, unsupported format, page without words, skipped canvases, notification contents) and ManifestReducerTests (skipped count).
  • ExecuteAsync_AltoReturnsNull_PageSkippedSilently and ExecuteAsync_VttFetchReturnsNull_PageSkippedSilently asserted the old silent behaviour, so they've been renamed and updated to expect the new error.
  • Unit tests pass (590). The E2E tests haven't been run against this change.

Database Migration

Note

  • Migration name: AddDiagnosticsToBuilderJob
  • What it does: adds skipped_canvases, pages_without_text_source and pages_without_words (integer, not null, default 0) to the jobs table
  • Breaking Change? No

🤖 Generated with Claude Code

@JackLewis-digirati

Copy link
Copy Markdown
Contributor Author

What does this change?

When a job completes with no words, the only information available today is totalWordCount: 0. Several different causes look identical, and most of them aren't recorded anywhere (dlcs/iiif-presentation#677 is an example of this being hard to diagnose). This PR records why pages produced no text, so callers can tell the user.

Page errors that were previously silent

These are added to errors on a completed job, one line per page, alongside the fetch exceptions that were already recorded there:

  • Text source not found or empty (e.g. a 404). Previously the page was skipped with a Debug log only. Now: {canvasId}: no text found at {textUri}. Applies to ALTO/hOCR, VTT and annotation pages.
  • Unsupported format. TextBuilder.AddPage / AddTranscriptPage now return false when no provider handles the page, instead of only logging a warning. Now: {canvasId}: unsupported text format at {textUri} (profile '…', format '…').

New counts

Three new fields on the job, the job response (GET /textbuilder/{id}) and JobCompletionNotification:

Field Meaning
skippedCanvases Canvases in the source manifest that weren't processed as pages. ManifestReducer.Reduce now returns this alongside the pages, in a new ReducedManifest record. Always 0 for sourceData jobs.
pagesWithoutTextSource Pages with no text source.
pagesWithoutWords Pages whose text source was read but had no words. Uses a new TextBuilder.WordCount.

These aren't errors: a manifest can include a cover or blank page with no OCR, and that shouldn't be reported as a failure. They're reset on reprocess.

Example

A completion notification for a two-canvas manifest where one ALTO file is missing and the other has no words:

{
  "jobId": "1/my-manifest",
  "status": "Completed",
  "finished": "2026-11-05T10:00:00+00:00",
  "totalPages": 2,
  "totalWordCount": 0,
  "errors": "https://example.org/canvases/c1: no text found at https://example.org/alto/c1.xml",
  "invocationCount": 1,
  "skippedCanvases": 0,
  "pagesWithoutTextSource": 0,
  "pagesWithoutWords": 1
}

Behaviour change

Jobs whose text files return 404 (or are empty) now complete with errors set, where previously errors was null. The job status is unchanged (Completed). Anything that treats a non-null errors on a completed job as a failure will see this.

Consumers

  • iiif-presentation is being updated to read the new counts and errors for completed jobs, and to show them as a warning on finishedPipelines.
  • The new notification fields are additive. Consumers that don't know about them can ignore them.

Tests

  • New TextBuilderTests, plus new tests in TextBuildJobTests (missing text, unsupported format, page without words, skipped canvases, notification contents) and ManifestReducerTests (skipped count).
  • ExecuteAsync_AltoReturnsNull_PageSkippedSilently and ExecuteAsync_VttFetchReturnsNull_PageSkippedSilently asserted the old silent behaviour, so they've been renamed and updated to expect the new error.
  • Unit tests pass (590). The E2E tests haven't been run against this change.

Database Migration

Note

  • Migration name: AddDiagnosticsToBuilderJob
  • What it does: adds skipped_canvases, pages_without_text_source and pages_without_words (integer, not null, default 0) to the jobs table
  • Breaking Change? No

@JackLewis-digirati
JackLewis-digirati marked this pull request as ready for review November 6, 2026 10:00
@JackLewis-digirati
JackLewis-digirati requested a review from a team as a code owner November 6, 2026 10:00
@JackLewis-digirati
JackLewis-digirati force-pushed the feature/improveErrorMessages branch from c261f21 to a72c673 Compare November 12, 2026 11:24
@JackLewis-digirati
JackLewis-digirati merged commit 98417ac into main Nov 12, 2026
4 checks passed
@JackLewis-digirati
JackLewis-digirati deleted the feature/improveErrorMessages branch November 12, 2026 11:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants