Skip to content

api_core: ResumableUploadSession.resume() raises ValueError when the server already finalized the upload #19114

Open

Description

@0z5a

Package: google-api-core (google.api_core.resumable_transfer), sync ResumableUploadSession and async AsyncResumableUploadSession.

What happens

If the last chunk of an upload is committed on the server but the client never reads the response (process killed, connection reset after the request was sent), the natural recovery is the one the generated samples suggest (gapic-generator feature_fragments.j2): save upload_session.upload_url and later call upload_session.resume(upload_url, stream) (or iter_resume). In that case the query command returns X-Goog-Upload-Status: final together with the final resource, but resume() raises:

ValueError: Upload completed without receiving a final response.

even though session.finished is True at that point and only the query request was sent. The final resource is dropped and the caller has no way to get it from the session.

Reproduction (no network, mocked transport; macOS arm64, Python 3.11, main)

import io
from unittest import mock
import requests
from google.api_core.resumable_transfer.upload import ResumableUploadSession

t = mock.create_autospec(requests.Session, instance=True)
t.request.side_effect = [mock.Mock(
    ok=True, status_code=200,
    headers={"X-Goog-Upload-Status": "final"},
    content=b'{"name":"obj","size":10}')]
s = ResumableUploadSession()
s.resume(upload_url="https://upload.example.com/s/1",
         stream=io.BytesIO(b"0123456789"), transport=t)
# ValueError: Upload completed without receiving a final response.
# s.finished == True, t.request.call_count == 1

For comparison, if the query instead reports active with X-Goog-Upload-Size-Received: 10, the session sends an empty upload, finalize request and resume() returns the response normally. AsyncResumableUploadSession.resume() has the same problem.

Why this looks unintended

  • The recovery path inside _transmit_all_chunks already treats a final query response as the final response (if self._state.finished: final_resp = recover_resp). iter_resume() calls _recover() directly, before _transmit_all_chunks, and discards its return value, so that branch is never reached for the initial query.
  • The gapic-generator system test test_resume_finalized_upload (packages/gapic-generator/tests/system/test_resumable_upload_resume.py) covers "recovering an already-finalized upload" and expects session.response to hold the deserialized resource. It gets there by driving the private recovery path directly, not through resume().
  • The one unit test that asserts the ValueError for resume, test_async_resume_already_finished_raises_value_error, mocks _recover to return nothing. It reads as coverage of the defensive branch rather than a statement that resuming a finished upload must fail.

Expected

resume() / iter_resume() should return or store the final response from the query when the server reports the upload as final, the same as the in-loop recovery path does.

I have a small fix with sync and async tests and can open a PR.

This issue was drafted with Claude Code (claude-opus-5-5); the results above are from the runs described.

Activity

  1. added a commit that references this issue on Nov 20, 2026
    a7c1899
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions