ConvertDocumentOptions default from_formats field potentially breaks compatibility with Docling Serve instances running older Docling versions

[jspast]

With the latest Docling 2.97.0 release, DoclingServiceClient convert*() and submit*() methods started to fail for me with the default Docling Serve Docker images (even the latest v1.21.0 with Docling 2.96.1). It took me a couple of hours to understand why. It did not help that the only feedback is Task submission failed. (status=422). Also could not find any information from the Docling Serve container logs, even with debug logs. Hopefully the logs can be improved in the future (docling-project/docling-serve#622).

Bug

Basically, the client now has a Docling version (2.97.0) with the introduction of EMAIL to the InputFormat enum (#3475) while the server (<2.97.0) does not. Then, calling DoclingServiceClient methods without overriding the options from_formats field will default to a list of all client InputFormat values which may not be known by the server.

Steps to reproduce

1. Start a Docling Serve instance with docling<2.97.0.
2. In a client with docling>=2.97.0, call DoclingServiceClient convert*() and submit*() methods.

[dosubot]

This is a valid compatibility concern. The root cause is that ConvertDocumentsOptions defaults from_formats to list(InputFormat) [1], which dynamically includes all enum members at class-definition time. When the EMAIL format was added to InputFormat in #3475 [2], any client running docling ≥2.97.0 will now include "email" in the default list sent to the server. An older docling-serve instance whose bundled docling package doesn't know about that enum value will reject it with a Pydantic validation error (the 422 you're seeing).

There's currently no version negotiation or graceful degradation between client and server — docling-serve delegates all from_formats validation directly to the upstream docling data models [3] [4].

Workaround: Explicitly pass a from_formats list that only contains formats the server supports, rather than relying on the default:

from docling.datamodel.base_models import InputFormat
from docling.datamodel.service.options import ConvertDocumentsOptions

options = ConvertDocumentsOptions(
    from_formats=[f for f in InputFormat if f != InputFormat.EMAIL]
)
client.convert(..., options=options)

As for a longer-term fix, a few options come to mind:

1. docling-serve could expose a capabilities/version endpoint so clients can filter unsupported formats automatically.
2. The server could ignore unknown from_formats values instead of failing validation (though that changes Pydantic strictness).
3. The default could be changed to None (meaning "all server-supported formats") rather than an explicit list of all client-known formats.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[jspast]

This has been fixed by commit ef50f45 (#3554). Thanks!