Skip to content

fix(client): report the error message of a failed async task - #776

Merged
edeandrea merged 3 commits into
docling-project:mainfrom
RaphaelFakhri:fix/async-task-error-message
Nov 12, 2026
Merged

edeandrea merged 3 commits into
docling-project:mainfrom
RaphaelFakhri:fix/async-task-error-message

Conversation

@RaphaelFakhri

Copy link
Copy Markdown
Contributor

What

When an async conversion or chunking task fails, the client builds the exception message from task_meta, which only holds document counts:

Async conversion failed for task task-1: Task failed: TaskStatusMetadata(numDocs=1, numProcessed=1, numSucceeded=0, numFailed=1)

Docling Serve reports the cause of the failure in the error_message field of the status poll response, but TaskStatusPollResponse doesn't map it, so the cause is lost.

How

  • TaskStatusPollResponse gains a nullable errorMessage field, mapped from error_message.
  • On FAILURE, AsyncOperations uses errorMessage when it is not blank. Otherwise it falls back to the task metadata, then to Task failed, as before.
  • whats-new.md has an entry for the change.

With the response above plus "error_message": "Input document is not valid", the message is now:

Async conversion failed for task task-1: Task failed: Input document is not valid

Tests

New failedTaskReportsTheErrorMessageOfTheServer in AbstractDoclingServeClientAsyncExecutorTests, so both Jackson backends run it. It stubs a failed task with error_message in WireMock and checks the root cause message.

  • Without the fix, the new test fails on both backends (the message holds TaskStatusMetadata(...)).
  • With the fix, ./gradlew --no-daemon :docling-serve-client:test --tests '*AsyncExecutorTests' :docling-serve-api:test spotlessCheck passes (14 and 246 tests, 0 failures). The existing failedTaskRunsEveryPollOnCustomExecutor test, which has neither field, still gets Task failed.

Related

Closes #775

Copilot AI balanced review requested due to automatic review settings November 4, 2026 09:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@edeandrea

Copy link
Copy Markdown
Contributor

@all-contributors add @RaphaelFakhri for bug, code

@allcontributors

Copy link
Copy Markdown
Contributor

@edeandrea

I've put up a pull request to add @RaphaelFakhri! 🎉

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

:java_duke: JaCoCo coverage report

Overall Project 52.29% 🟢

There is no coverage information present for the Files changed

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
TestsPassed ☑️SkippedFailed ❌️
Gradle Test Results (all modules & JDKs)1871 ran1866 passed0 skipped5 failed
TestResult
Gradle Test Results (all modules & JDKs)
ai.docling.serve.client.DoclingServeJackson3ClientTests
DoclingServeJackson3ClientTests.initializationError❌ failure
ai.docling.serve.client.DoclingServeJackson2ClientTests
DoclingServeJackson2ClientTests.initializationError❌ failure
ai.docling.serve.client.DoclingServeJackson3ClientTests
DoclingServeJackson3ClientTests.initializationError❌ failure
ai.docling.serve.client.DoclingServeJackson2ClientTests
DoclingServeJackson2ClientTests.initializationError❌ failure
ai.docling.serve.client.DoclingServeJackson2ClientTests
DoclingServeJackson2ClientTests.initializationError❌ failure

@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown

HTML test reports are available as workflow artifacts (zipped HTML).

• Download: Artifacts for this run

@edeandrea edeandrea left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, @RaphaelFakhri — a clear issue report and the fix goes in at the right layer. I appreciate that you went looking at what the poll response actually carries rather than just reworking the message text.

Worth recording something I checked while reviewing, because it makes the change look better than the description claims. Upstream TaskStatusResponse actually carries two failure fields, error_message and failure, and I went in half-expecting to ask why you'd picked the thinner one. It turns out to be the opposite:

Orchestrator error_message failure
local (what DoclingServeContainer runs) yes no
RQ yes no
Ray yes yes

Only the Ray dispatcher populates failure, and it only exists from docling-serve v1.25.0, whereas error_message comes back from every tag in our compatibility table down to v1.18.0. So this picks the one field that works for everybody. I've opened #778 to track the other one separately.

Three requests below, all in tests and docs — the production change itself is good as it stands. Two further comments are just me confirming things are right, so you don't have to wonder whether they're veiled asks.

Copilot AI balanced review requested due to automatic review settings November 6, 2026 20:46

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@edeandrea edeandrea left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @RaphaelFakhri — this is great work. Every request from the last round was addressed exactly as asked: the failure tests now live in their own AsyncTaskFailureTests class, the four extra cases pin the whole FAILURE decision tree (including the blank-message guard and the chunk path), and the docs note about error sanitization will save someone a confusing bug report later. I also appreciated you confirming the new tests fail against the old code — that's exactly the kind of check that makes a review easy.

I merged this onto current main locally and the new tests pass on both Jackson backends, with spotless clean. Approving and setting to auto-merge. Thanks again for the contribution! 🎉

@edeandrea
edeandrea enabled auto-merge (squash) November 12, 2026 14:38
Signed-off-by: Raphael Fakhri <153192858+RaphaelFakhri@users.noreply.github.com>
Signed-off-by: Raphael Fakhri <153192858+RaphaelFakhri@users.noreply.github.com>
Signed-off-by: Raphael Fakhri <153192858+RaphaelFakhri@users.noreply.github.com>
@edeandrea
edeandrea force-pushed the fix/async-task-error-message branch from 1c7fb93 to 10958f9 Compare November 12, 2026 14:39
Copilot AI balanced review requested due to automatic review settings November 12, 2026 14:39

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@edeandrea
edeandrea merged commit ce7bd6c into docling-project:main Nov 12, 2026
25 of 29 checks passed
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.

Async task failure hides the error message returned by Docling Serve

3 participants