Skip to content

fix(client): raise the server message after retrying HTTP 500 - #433

Open
PDGGK wants to merge 1 commit into
apache:mainfrom
PDGGK:fix/client-retry-server-message
Open

PDGGK wants to merge 1 commit into
apache:mainfrom
PDGGK:fix/client-retry-server-message

Conversation

@PDGGK

@PDGGK PDGGK commented Nov 13, 2026

Copy link
Copy Markdown

Purpose of the PR

When the server answers a GET, PUT or DELETE with HTTP 500, the Python client hides the server's message. client.variable().set("d", {"a": 1}) fails with requests.exceptions.RetryError: HTTPConnectionPool(...): Max retries exceeded with url: /graphspaces/DEFAULT/graphs/hugegraph/variables/d (Caused by ResponseError('too many 500 error responses')). The server's actual answer is "Graph variable value [{a=1}] is of type class java.util.LinkedHashMap is not supported". A list that contains a map behaves the same. I reproduced this on main and with the released hugegraph-python 1.7.1 against hugegraph/hugegraph:latest (server 1.8.0).

HGraphSession retries 500, 502 and 504 through a urllib3 Retry, which applies to GET, PUT and DELETE but not POST. When the retries run out, urllib3 raises MaxRetryError by default, and requests turns it into RetryError. ResponseValidation never sees the response, so the message it would put into ServerError is lost, and the caller gets a requests exception instead of the client's own type. POST requests and 4xx answers on the same session already raise ServerError with the server's message. The README says server errors surface through the existing exception types, and the MCP error mapping classifies ServerError by that message.

Main Changes

The Retry now sets raise_on_status=False. The retries happen as before (with the default retries=3 a PUT that keeps failing is still sent four times, while a POST is sent once), and once they are spent urllib3 returns the last response, which ResponseValidation turns into ServerError with the server's message. The retry-free policy used by TaskManager.wait() is unchanged.

Tests: test_retried_server_errors_raise_the_server_message runs a local HTTP server that answers every GET, PUT and DELETE with a HugeGraph-style 500 body, and checks that each method raises ServerError with the message after the configured retries (three requests with retries=2). The integration test test_set_unsupported_value_raises_server_message stores a map in a graph variable on a live server.

Verifying these changes

  • Trivial rework / code cleanup without any test coverage. (No Need)
  • Already covered by existing tests, such as (please modify tests here).
  • Need tests and can be verified as follows:
    • uv run pytest hugegraph-python-client/src/tests -m "unit or contract": 168 passed, 3 skipped.
    • uv run pytest hugegraph-python-client/src/tests -m "integration and hugegraph": 71 passed against hugegraph/hugegraph:latest (server 1.8.0).
    • With only huge_requests.py reverted, the four new test cases fail with the RetryError above.
    • A script that calls variable().set() with a map and with a list containing a map gets RetryError on main and on 1.7.1, and ServerError: Server Exception: Graph variable value [{a=1}] is of type class java.util.LinkedHashMap is not supported with this change, after the same 0.6 s of retries.
    • ruff format --check ., ruff check ., ty check hugegraph-python-client/src/pyhugegraph and python3 scripts/client_api.py --check pass.
    • The hugegraph-mcp selection from its CI job (904 passed) and the hugegraph-llm unit selection (1282 passed, 3 skipped) pass, as they do on main.

I ran everything on Python 3.12 with uv 0.13.6, and only against server 1.8.0, not the 1.7.0 compatibility image. I did not test a 502 or 504 coming from a proxy; those now also raise ServerError with the proxy's body instead of RetryError. One caller sees a different type: SchemaManager.run() in hugegraph-llm wraps RequestException from get_schema() as "Failed to connect to HugeGraph", so a 500 there now arrives as ServerError, the same way a 400 or 404 already does. Connection errors and timeouts are still RequestException. vermeer-python-client builds the same Retry and is not changed here.

Does this PR potentially affect the following parts?

  • Dependencies
  • Modify configurations
  • The public API
  • Other affects (typed here)
  • Nope

GET, PUT and DELETE requests are retried on 500, 502 and 504. When the
retries ran out, urllib3 raised MaxRetryError and requests turned it into
RetryError ("too many 500 error responses"), so ResponseValidation never
saw the response and the server's message was lost. For example,
variable().set("d", {"a": 1}) hid "Graph variable value [{a=1}] ... is
not supported".

Set raise_on_status=False so the last response is returned after the
retries and ResponseValidation raises ServerError with the server's
message, as it already does for POST and for 4xx responses.

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: no. Score: 9/10. Summary: raise_on_status=False returns the last 5xx response to ResponseValidation, so retried GET, PUT and DELETE raise ServerError with the server message while retry counts and connection errors stay unchanged; the contract test fails on the base with RetryError and passes here.

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Score: 9.1/10 · Confidence: high

Blocking: no

Summary

The retry policy now returns the final retryable 5xx response to the existing validator, preserving the client ServerError contract and server message.

Evidence

Reviewed the changed Retry configuration, HGraphSession request-to-validator path, VariableManager calls, exact-head CI, and all current PR feedback.

Validation notes

Static source review only; no local live HugeGraph/proxy 502 or 504 reproduction was run.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants