mlflow/mlflow · error · MlflowException

Deployments proxy request failed with error code {response.s

Error message

Deployments proxy request failed with error code {response.status_code}. Error message: {response.text}

What it means

The deployments proxy forwards the request to the target AI Gateway server via requests.request(). If the upstream response status is not 200, the handler wraps the upstream status code and response body text into an MlflowException and re-raises it. The error_code is the raw upstream HTTP status, so a 404 or 500 from the gateway surfaces here.

Source

Thrown at mlflow/server/handlers.py:2469

            )


@catch_mlflow_exception
def gateway_proxy_handler():
    target_uri = MLFLOW_DEPLOYMENTS_TARGET.get()
    if not target_uri:
        # Pretend an empty gateway service is running
        return {"endpoints": []}

    args = request.args if request.method == "GET" else request.json
    gateway_path = args.get("gateway_path")
    _validate_gateway_path(request.method, gateway_path)
    json_data = args.get("json_data", None)
    response = requests.request(request.method, f"{target_uri}/{gateway_path}", json=json_data)
    if response.status_code == 200:
        return response.json()
    else:
        raise MlflowException(
            message=f"Deployments proxy request failed with error code {response.status_code}. "
            f"Error message: {response.text}",
            error_code=response.status_code,
        )


@catch_mlflow_exception
@_disable_if_artifacts_only
def create_promptlab_run_handler():
    def assert_arg_exists(arg_name, arg):
        if not arg:
            raise MlflowException(
                message=f"CreatePromptlabRun request must specify {arg_name}.",
                error_code=INVALID_PARAMETER_VALUE,
            )

    _validate_content_type(request, ["application/json"])

View on GitHub (pinned to 6a27f2decc)

Solutions

Read the 'Error message' in the exception — it contains the upstream response text with the real cause.
Verify the gateway server URL (target_uri) is correct and reachable with curl.
Confirm the endpoint name in 'gateway/{name}/invocations' still exists — use GET api/2.0/endpoints to list endpoints.
Fix the request payload per the gateway's schema, and retry on 5xx.

Example fix

// before
client.invoke('my-ep')  # endpoint deleted -> 404 wrapped by proxy
// after
endpoints = requests.get(f'{gateway_uri}/api/2.0/endpoints').json()
assert any(e['name'] == 'my-ep' for e in endpoints['endpoints'])
client.invoke('my-ep')

Defensive patterns

Strategy: retry

Validate before calling

import requests
if requests.get(f'{target_uri}/api/2.0/endpoints', timeout=5).status_code != 200:
    raise RuntimeError(f'Gateway at {target_uri} is not healthy')

Try / catch

from mlflow.exceptions import MlflowException
try:
    result = proxy_invoke(endpoint, payload)
except MlflowException as e:
    if e.error_code in (500, 502, 503, 504):
        result = proxy_invoke(endpoint, payload)  # retry transient
    else:
        log.error('Gateway rejected: %s', e.message)
        raise

Prevention

Health-check the gateway server before invoking endpoints.
Validate endpoint names against GET api/2.0/endpoints.
Log the upstream error text included in the message before retrying.
Validate payloads against the endpoint's declared schema client-side.

When it happens

Trigger: The upstream gateway endpoint does not exist (404), the gateway rejects the payload (400/422), the gateway errors internally (5xx), or target_uri is wrong so the upstream route isn't found.

Common situations: Misconfigured target_uri for the gateway server, gateway endpoint deleted or renamed while clients still invoke it, invalid request payload failing gateway-side validation, gateway server down or crashing.

Related errors

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/2f913a4f2f92a49e. Report an issue: GitHub.