[Bugfix] Return HTTP 422 for unprocessable image URLs instead of 500 (#47165)

Signed-off-by: Alexis Kinsella <alexis.kinsella@gmail.com>
This commit is contained in:
Alexis K.
2026-07-06 11:56:23 +00:00
committed by GitHub
parent ba22152096
commit 40cc2e8327
5 changed files with 288 additions and 12 deletions
@@ -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
+2 -1
View File
@@ -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
@@ -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
+34
View File
@@ -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
+84 -10
View File
@@ -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