zylon-ai/private-gpt · error · ValueError

Task failed with status: {status.task_status}

Error message

Task failed with status: {status.task_status}

What it means

Raised by AsyncDoclingClient._wait_for_completion when the Docling server reports a terminal task_status of 'failure' or 'skipped' for a submitted async conversion task. The client had successfully submitted the file to /convert/source/async and received a task_id, but the server-side conversion itself failed or the task was skipped. This is a server-side outcome being surfaced to the caller as a ValueError; the message includes the exact status string.

Source

Thrown at private_gpt/components/readers/docling/api_clients.py:498

            session.get(
                f"{self.base_url}/result/{task_id}", headers=headers
            ) as response,
        ):
            response.raise_for_status()
            result = await response.json()
            return DoclingApiOutputModel(**result)

    async def _wait_for_completion(self, task_id: str) -> DoclingApiOutputModel:
        start_time = time.time()
        while not self.poll_timeout or time.time() - start_time < self.poll_timeout:
            status = await self._poll_task_status(task_id)
            if status.task_status == "success":
                task_result: DoclingApiOutputModel = await self._get_task_result(
                    task_id
                )
                return task_result
            if status.task_status in ["failure", "skipped"]:
                raise ValueError(f"Task failed with status: {status.task_status}")

            await asyncio.sleep(self.poll_interval)

        raise TimeoutError(f"Task did not complete within {self.poll_timeout} seconds")

    @retry(
        is_async=True,
        tries=_MAX_RETRIES,
        jitter=_JITTER,
        logger=logger,
        exceptions=ResourceNotFoundError,
    )
    async def convert_from_bytes(
        self, file_name: str, file_bytes: bytes, **kwargs: Any
    ) -> DoclingApiOutputModel:
        task_id = await self._submit_task(file_name, file_bytes, **kwargs)
        return await self._wait_for_completion(task_id)

View on GitHub (pinned to 4a030776a3)

Solutions

1. Check the Docling server logs for the actual conversion error for that task_id — this exception only mirrors the server's status.
2. Verify the conversion options sent (pdf_backend, from_formats, to_formats, ocr settings) are supported by your Docling server version; try pdf_backend='dlparse_v2' defaults.
3. Test the same file directly against the server API (POST /convert/source/async then GET /status/poll/{id}) to isolate whether the file itself is the problem.
4. Try the file with a different pdf_backend or with do_ocr toggled, since OCR crashes are a frequent cause of 'failure' status.
5. If 'skipped' recurs, check for server restarts or queue misconfiguration between submission and polling.

Example fix

# before
result = await client.convert_from_bytes(name, data)

# after
try:
    result = await client.convert_from_bytes(name, data)
except ValueError as e:
    if 'Task failed with status' in str(e):
        logger.error("Docling server rejected %s: %s", name, e)
        raise DocumentUnprocessableError(name) from e
    raise

try:
    result = await client.convert_from_bytes(file_name, file_bytes)
except ValueError as e:
    status = str(e).rsplit(":", 1)[-1].strip()  # 'failure' or 'skipped'
    if status in ("failure", "skipped"):
        quarantine_file(file_name, reason=f"docling task {status}")
        return None  # skip, do not retry: terminal server-side outcome
    raise

When it happens

Trigger: Calling convert_from_bytes on AsyncDoclingClient (i.e., docling async ingestion) where the Docling server processes the task and returns task_status == 'failure' (conversion error, e.g., corrupt PDF backend, invalid options) or 'skipped' (task superseded/removed, e.g., server restart with queue cleanup or duplicate job).

Common situations: Corrupt or password-protected PDFs; unsupported from_formats/pdf_backend options (e.g., pdf_backend not available on the server build); Docling server version mismatch where options like do_code_enrichment are rejected at conversion time; server restart purging the task queue; GPU/OCR model crash on the server while processing a specific document.

Related errors

• API base URL and poll interval must be provided in async mod
• Task did not complete within {self.poll_timeout} seconds
• Document conversion failed with status: {conversion_result.s
• INVALID_REQUEST_ERROR
• No items returned from astream_structured_predict

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/792861970fc9a0b4. Report an issue: GitHub.