[Zhuoxi2000]

Linked issue: #1059

Purpose of change

A chat message with media sent to a provider that cannot carry it now fails with UnsupportedContentBlockException / UnsupportedContentBlockError instead of being sent as its text alone. This is the last Phase 2 item of #1059, "explicit unsupported-block errors for providers not yet migrated", after #1164 (OpenAI Chat Completions, Azure OpenAI, vLLM) and #1178 (Ollama).

Covered: Java Anthropic, Gemini, Amazon Bedrock, IBM watsonx.ai and OpenAI Responses; Python Anthropic, DashScope and IBM watsonx.ai.

Runtime flow

1. Each covered connection's chat() first calls UnsupportedContentBlockException.rejectMedia(provider, messages) (Java) or UnsupportedContentBlockError.reject_media(provider, messages) (Python).
2. The first media block in any message, of any role, throws; text-only messages go on to the unchanged conversion and request.

Key decisions

• Reject rather than send the text projection: dropping an image silently changes the question the model answers, which is what [Feature] Multimodal content blocks in ChatMessage #1059 asked to avoid.
• One shared helper next to the forBlock / for_block factory from [integration][java][python] Send multimodal user messages through OpenAI Chat Completions #1164, so every provider reports the same message: {provider} cannot send an image block (image/png, base64 source): this integration sends text only.
• The check runs at the start of chat(), before any try that wraps provider errors, so callers receive the documented type (the issue [integration][java][python] Send user images to Ollama #1178 review caught for Ollama).
• Native media support for these providers stays in the [Feature] Multimodal content blocks in ChatMessage #1059 follow-ups; this PR only makes the current gap explicit.

Behavioral Semantics

Interaction decisions

Messages	Result
text only, any roles	unchanged request
any media block, any role	UnsupportedContentBlockException / UnsupportedContentBlockError; nothing is sent

Behavioral contracts

1. A covered connection throws for the first media block before sending anything.
2. The error is the documented type itself when it leaves chat(), not a wrapper.
3. The message names the provider, block type, media type and source type, never the data or URL.
4. Requests without media are unchanged.

Java and Python behave identically.

Failure behavior

• Media in a message: thrown before any request is built or sent; the chat action's error strategy applies, and RETRY fails the same way each attempt since the error is deterministic.
• No other failure path changes.

Tests

Contract	Java	Python
1, 2, 3	testMediaBlocksFailExplicitly in AnthropicChatModelConnectionTest, GeminiChatModelConnectionTest, BedrockChatModelConnectionTest, WatsonxChatModelConnectionTest (both overloads), OpenAIResponsesModelConnectionTest, each through chat() and asserting the exact message	test_text_only_providers_reject_media.py, parametrized over Anthropic, DashScope and watsonx, through chat()
4	the existing request-building tests of each connection	the existing provider tests

Not verified: a live provider; the check runs before any request, so none is needed for these contracts.

Implementation invariants and supporting evidence

• rejectMedia / reject_media only read getBlocks() / .blocks and use forBlock / for_block, so messages match [integration][java][python] Send multimodal user messages through OpenAI Chat Completions #1164 and [integration][java][python] Send user images to Ollama #1178.
• Every Java chat() overload reaches the check: Anthropic, Bedrock, Gemini and (since 9b2cc1f) watsonx route the three-argument overload into the four-argument one; OpenAI Responses checks in the three-argument overload, which the base four-argument one calls.
• Verified locally: the five Java connection test classes and spotless; Python Anthropic, DashScope, watsonx and chat-message tests, with ruff.

API

New public helpers: UnsupportedContentBlockException.rejectMedia(String, List<ChatMessage>) (Java) and UnsupportedContentBlockError.reject_media(provider, messages) (Python).

Compatibility: text-only requests are unchanged. A message with media to one of these providers used to be sent as its text only; it now fails.

Documentation

• doc-needed
• doc-not-needed
• doc-included

The provider-support note in chat_models.md names these integrations and the error; the Bedrock limitation note says media raises.

Was this patch authored or co-authored using generative AI tooling?

• Yes
• No

If yes, include a Generated-by: <tool name and version> (<model name and version>) line, for example Generated-by: Claude Code 2.1.226 (Claude Opus 4.6), in the commit message so it reaches Git history. Repeat the same line here for reviewer visibility. See the ASF generative tooling guidance.

Generated-by: Claude Code 2.1.259 (Claude Opus 5.5)

[wenjin272]

Thanks for the contribution and for making unsupported media handling explicit across these integrations! I found one remaining path in Java watsonx that bypasses the new check; please see the inline comment.

[wenjin272]

The media check only runs in the four-argument chat(), but BaseChatModelSetup.chat() calls the three-argument overload, which delegates directly to doChat(). That path still silently drops media via getText() and sends only the text.

Could we delegate the three-argument overload to the four-argument one and add a regression test for that entry point? I reproduced this with a local HTTP endpoint: a text-plus-image message was sent as text only without throwing.

[Zhuoxi2000]

Good catch; fixed in a7487b0, the three-argument chat() now delegates, with a regression test.

[Zhuoxi2000]

The cross-language failure is a Maven download error; could someone rerun that job?

[wenjin272]

Thanks for the update. LGTM.

There are some conflicts with the main branch that need to be resolved.

[Zhuoxi2000]

Rebased onto main and resolved the DashScope rename conflict; thanks for the review!