From 40cc2e83278f9280d80c2527fe03be1c5aa8c91f Mon Sep 17 00:00:00 2001 From: "Alexis K." <322456+akinsella@users.noreply.github.com> Date: Mon, 6 Jul 2026 13:56:23 +0200 Subject: [PATCH] [Bugfix] Return HTTP 422 for unprocessable image URLs instead of 500 (#47165) Signed-off-by: Alexis Kinsella --- .../media/test_unprocessable_entity_error.py | 159 ++++++++++++++++++ vllm/entrypoints/openai/api_server.py | 3 +- .../entrypoints/serve/utils/error_response.py | 10 +- vllm/exceptions.py | 34 ++++ vllm/multimodal/media/connector.py | 94 +++++++++-- 5 files changed, 288 insertions(+), 12 deletions(-) create mode 100644 tests/multimodal/media/test_unprocessable_entity_error.py diff --git a/tests/multimodal/media/test_unprocessable_entity_error.py b/tests/multimodal/media/test_unprocessable_entity_error.py new file mode 100644 index 0000000000..8be70383b8 --- /dev/null +++ b/tests/multimodal/media/test_unprocessable_entity_error.py @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: Apache-2.0 +# SPDX-FileCopyrightText: Copyright contributors to the vLLM project + +"""Tests for VLLMUnprocessableEntityError and media fetch error handling. + +Verifies that unprocessable image URLs (404, 403, DNS failures, etc.) return +HTTP 422 instead of 500. +""" + +from http import HTTPStatus +from unittest.mock import AsyncMock, MagicMock, patch + +import aiohttp +import pytest + +from vllm.entrypoints.serve.utils.error_response import create_error_response +from vllm.exceptions import VLLMUnprocessableEntityError +from vllm.multimodal.media import MediaConnector + + +class TestVLLMUnprocessableEntityError: + """Tests for VLLMUnprocessableEntityError exception.""" + + def test_creation(self): + exc = VLLMUnprocessableEntityError("Test error") + assert str(exc) == "Test error" + assert exc.parameter is None + + def test_creation_with_parameter_and_value(self): + exc = VLLMUnprocessableEntityError( + "Test error", + parameter="image_url", + value="https://example.com/image.jpg", + ) + assert "parameter=image_url" in str(exc) + assert "value=https://example.com/image.jpg" in str(exc) + + def test_is_value_error_subclass(self): + exc = VLLMUnprocessableEntityError("Test") + assert isinstance(exc, ValueError) + + +class TestMediaConnectorErrorHandling: + """Tests for MediaConnector error handling.""" + + @pytest.mark.asyncio + async def test_fetch_image_async_404(self): + connector = MediaConnector() + + with patch.object( + connector.connection, "async_get_bytes", new_callable=AsyncMock + ) as mock_get: + mock_get.side_effect = aiohttp.ClientResponseError( + request_info=MagicMock(), + history=(), + status=404, + message="Not Found", + ) + + with pytest.raises(VLLMUnprocessableEntityError) as exc_info: + await connector.fetch_image_async("https://example.com/missing.jpg") + + assert exc_info.value.parameter == "image_url" + + @pytest.mark.asyncio + async def test_fetch_image_async_dns_error(self): + """DNS errors are transient and should remain as-is for retry.""" + connector = MediaConnector() + + with patch.object( + connector.connection, "async_get_bytes", new_callable=AsyncMock + ) as mock_get: + mock_get.side_effect = aiohttp.ClientConnectorDNSError( + connection_key=MagicMock(), + os_error=MagicMock(), + ) + + with pytest.raises(aiohttp.ClientConnectorDNSError) as exc_info: + await connector.fetch_image_async( + "https://nonexistent.example/image.jpg" + ) + + assert isinstance(exc_info.value, aiohttp.ClientConnectorDNSError) + + @pytest.mark.asyncio + async def test_fetch_image_async_500_preserved(self): + """5xx errors should remain as server errors.""" + connector = MediaConnector() + + with patch.object( + connector.connection, "async_get_bytes", new_callable=AsyncMock + ) as mock_get: + mock_get.side_effect = aiohttp.ClientResponseError( + request_info=MagicMock(), + history=(), + status=500, + message="Internal Server Error", + ) + + with pytest.raises(aiohttp.ClientResponseError) as exc_info: + await connector.fetch_image_async("https://example.com/image.jpg") + + assert exc_info.value.status == 500 + + def test_fetch_image_404(self): + connector = MediaConnector() + + with patch.object( + connector.connection, "get_bytes", new_callable=MagicMock + ) as mock_get: + mock_get.side_effect = aiohttp.ClientResponseError( + request_info=MagicMock(), + history=(), + status=404, + message="Not Found", + ) + + with pytest.raises(VLLMUnprocessableEntityError) as exc_info: + connector.fetch_image("https://example.com/missing.jpg") + + assert exc_info.value.parameter == "image_url" + + def test_fetch_image_connection_error(self): + """Connection errors are transient and should remain as-is for retry.""" + connector = MediaConnector() + + with patch.object( + connector.connection, "get_bytes", new_callable=MagicMock + ) as mock_get: + mock_get.side_effect = aiohttp.ClientConnectionError("Connection refused") + + with pytest.raises(aiohttp.ClientConnectionError) as exc_info: + connector.fetch_image("https://example.com/image.jpg") + + assert isinstance(exc_info.value, aiohttp.ClientConnectionError) + + +class TestErrorResponse: + """Tests for error response creation.""" + + def test_unprocessable_entity_returns_422(self): + exc = VLLMUnprocessableEntityError( + "Failed to fetch media from URL: Cannot connect", + parameter="image_url", + value="https://example.com/image.jpg", + ) + + response = create_error_response(exc) + + assert response.error.code == HTTPStatus.UNPROCESSABLE_ENTITY.value + assert response.error.type == "UnprocessableEntityError" + assert response.error.param == "image_url" + + def test_unprocessable_entity_message(self): + exc = VLLMUnprocessableEntityError("Test error message") + response = create_error_response(exc) + + assert response.error.message == "Test error message" + assert response.error.code == 422 diff --git a/vllm/entrypoints/openai/api_server.py b/vllm/entrypoints/openai/api_server.py index 6fb27c365d..71dc508a34 100644 --- a/vllm/entrypoints/openai/api_server.py +++ b/vllm/entrypoints/openai/api_server.py @@ -51,7 +51,7 @@ from vllm.entrypoints.serve.utils.server_utils import ( log_response, validation_exception_handler, ) -from vllm.exceptions import VLLMValidationError +from vllm.exceptions import VLLMUnprocessableEntityError, VLLMValidationError from vllm.logger import init_logger from vllm.reasoning import ReasoningParserManager from vllm.renderers.online_derenderer import OnlineDerenderer @@ -245,6 +245,7 @@ def build_app( app.exception_handler(EngineDeadError)(engine_error_handler) app.exception_handler(GenerationError)(generation_error_handler) app.exception_handler(VLLMValidationError)(exception_handler) + app.exception_handler(VLLMUnprocessableEntityError)(exception_handler) app.exception_handler(Exception)(exception_handler) # Ensure --api-key option from CLI takes precedence over VLLM_API_KEY diff --git a/vllm/entrypoints/serve/utils/error_response.py b/vllm/entrypoints/serve/utils/error_response.py index 4dea1513a4..fc17a75c75 100644 --- a/vllm/entrypoints/serve/utils/error_response.py +++ b/vllm/entrypoints/serve/utils/error_response.py @@ -27,12 +27,20 @@ def create_error_response( "create_error_response called with %s: %s", type(exc).__name__, exc ) - from vllm.exceptions import VLLMNotFoundError, VLLMValidationError + from vllm.exceptions import ( + VLLMNotFoundError, + VLLMUnprocessableEntityError, + VLLMValidationError, + ) if isinstance(exc, VLLMValidationError): err_type = "BadRequestError" status_code = HTTPStatus.BAD_REQUEST param = exc.parameter + elif isinstance(exc, VLLMUnprocessableEntityError): + err_type = "UnprocessableEntityError" + status_code = HTTPStatus.UNPROCESSABLE_ENTITY + param = exc.parameter elif isinstance(exc, VLLMNotFoundError): err_type = "NotFoundError" status_code = HTTPStatus.NOT_FOUND diff --git a/vllm/exceptions.py b/vllm/exceptions.py index 931040b8ce..4112c3de24 100644 --- a/vllm/exceptions.py +++ b/vllm/exceptions.py @@ -64,3 +64,37 @@ class LoRAAdapterNotFoundError(VLLMNotFoundError): def __str__(self): return self.message + + +class VLLMUnprocessableEntityError(ValueError): + """vLLM-specific error for unprocessable entity requests. + + This exception is raised when the request content is invalid or cannot be + processed, such as when an image URL points to a non-existent or inaccessible + resource (404, 403, DNS failure, etc.). + + Args: + message: The error message describing the unprocessable entity. + parameter: Optional parameter name that failed validation. + value: Optional value that was rejected during validation. + """ + + def __init__( + self, + message: str, + *, + parameter: str | None = None, + value: Any = None, + ) -> None: + super().__init__(message) + self.parameter = parameter + self.value = value + + def __str__(self): + base = super().__str__() + extras = [] + if self.parameter is not None: + extras.append(f"parameter={self.parameter}") + if self.value is not None: + extras.append(f"value={self.value}") + return f"{base} ({', '.join(extras)})" if extras else base diff --git a/vllm/multimodal/media/connector.py b/vllm/multimodal/media/connector.py index 582b6fde56..a440e69ef1 100644 --- a/vllm/multimodal/media/connector.py +++ b/vllm/multimodal/media/connector.py @@ -13,14 +13,17 @@ from pathlib import Path from typing import Any, TypeVar from urllib.request import url2pathname +import aiohttp import numpy as np import numpy.typing as npt +import requests import torch from PIL import Image, UnidentifiedImageError from urllib3.util import Url, parse_url import vllm.envs as envs from vllm.connections import HTTPConnection, global_http_connection +from vllm.exceptions import VLLMUnprocessableEntityError from vllm.logger import init_logger from vllm.multimodal.video import get_video_loader_backend_for_processor from vllm.utils.registry import ExtensionManager @@ -48,6 +51,65 @@ MODALITY_IO_MAP: dict[str, type[MediaIO]] = { } +def _wrap_media_fetch_error( + url: str, exc: Exception +) -> VLLMUnprocessableEntityError | Exception: + """Convert media fetch exceptions to VLLMUnprocessableEntityError. + + This handles HTTP errors that indicate the media resource is invalid + (4xx responses except 408/429, malformed URLs) and converts them to a + 422 Unprocessable Entity error instead of 500. + + Transient errors (5xx, 408, 429, DNS failures, connection errors, + timeouts) are returned as-is to allow retry logic to handle them + appropriately. + + Returns: + VLLMUnprocessableEntityError for permanent client errors (4xx except + 408/429, invalid URL) + Original exception for transient errors (5xx, 408, 429, network blips) + or other exceptions + """ + if isinstance(exc, aiohttp.ClientResponseError): + if exc.status in (408, 429): + return exc + if exc.status < 500: + return VLLMUnprocessableEntityError( + f"Failed to fetch media from URL: HTTP {exc.status} error", + parameter="image_url", + value=url, + ) + return exc + + if isinstance(exc, requests.exceptions.HTTPError): + if exc.response is not None: + status_code = exc.response.status_code + if status_code in (408, 429): + return exc + if status_code < 500: + return VLLMUnprocessableEntityError( + f"Failed to fetch media from URL: HTTP {status_code} error", + parameter="image_url", + value=url, + ) + return exc + + if isinstance(exc, requests.exceptions.InvalidURL): + return VLLMUnprocessableEntityError( + "Failed to fetch media from URL: Invalid URL format", + parameter="image_url", + value=url, + ) + + if isinstance(exc, ValueError): + return VLLMUnprocessableEntityError( + "Failed to fetch media from URL: Invalid URL", + parameter="image_url", + value=url, + ) + return exc + + def merge_media_io_kwargs( defaults: dict[str, dict[str, Any]] | None, overrides: dict[str, dict[str, Any]] | None, @@ -303,11 +365,17 @@ class MediaConnector: return media_io.load_bytes(cached) connection = self.connection - data = connection.get_bytes( - url_spec.url, - timeout=fetch_timeout, - allow_redirects=envs.VLLM_MEDIA_URL_ALLOW_REDIRECTS, - ) + try: + data = connection.get_bytes( + url_spec.url, + timeout=fetch_timeout, + allow_redirects=envs.VLLM_MEDIA_URL_ALLOW_REDIRECTS, + ) + except Exception as e: + wrapped = _wrap_media_fetch_error(url, e) + if isinstance(wrapped, VLLMUnprocessableEntityError): + raise wrapped from e + raise self._put_cached_bytes(url, data) return media_io.load_bytes(data) @@ -348,11 +416,17 @@ class MediaConnector: return await future connection = self.connection - data = await connection.async_get_bytes( - url_spec.url, - timeout=fetch_timeout, - allow_redirects=envs.VLLM_MEDIA_URL_ALLOW_REDIRECTS, - ) + try: + data = await connection.async_get_bytes( + url_spec.url, + timeout=fetch_timeout, + allow_redirects=envs.VLLM_MEDIA_URL_ALLOW_REDIRECTS, + ) + except Exception as e: + wrapped = _wrap_media_fetch_error(url, e) + if isinstance(wrapped, VLLMUnprocessableEntityError): + raise wrapped from e + raise await loop.run_in_executor( global_thread_pool, self._put_cached_bytes, url, data