fix: raise on an empty HTTP-200 split chunk in NDJSON mode (0.46.1)

In NDJSON elements-file mode a split-PDF chunk that returned 200 with an
empty body was logged and skipped, so the combined elements_file was short
by those pages while the call still succeeded. `split_pdf_allow_failed`
does not cover it -- an empty 200 counts as a successful chunk -- and
`combine_chunk_files_to_ndjson` returns only a path, so nothing downstream
could detect the truncation.

Recombination now raises `EmptyChunkResponseError` (a `ValueError`) instead,
matching the buffered path, which raises `JSONDecodeError` on the same
response. An empty JSON array is still accepted: `[]` and an empty body are
different responses on the wire and only the latter is a defect.

Refs ML-1672.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: badGarnet

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.46.1
+
+### Fixes
+* Fail loudly when a split-PDF chunk returns HTTP 200 with an empty body in NDJSON elements-file mode. The chunk used to be logged and skipped, so the combined `elements_file` was silently short by those pages while the call still returned 200 — and `split_pdf_allow_failed=False` did not catch it, because an empty 200 counts as a successful chunk. Recombination now raises `EmptyChunkResponseError` (a `ValueError`), matching the buffered path, which raises `JSONDecodeError` on the same response. A chunk that legitimately produced no elements returns an empty JSON array and is still accepted.
+
 ## 0.46.0
 
 ### Features

RELEASES.md

@@ -1251,3 +1251,13 @@ Based on:
 - [python v0.46.0] .
 ### Releases
 - [PyPI v0.46.0] https://pypi.org/project/unstructured-client/0.46.0 - .
+
+## 2026-08-04 00:00:00
+### Changes
+Based on:
+- OpenAPI Doc  
+- Speakeasy CLI 1.601.0 (2.680.0) https://github.com/speakeasy-api/speakeasy
+### Generated
+- [python v0.46.1] .
+### Releases
+- [PyPI v0.46.1] https://pypi.org/project/unstructured-client/0.46.1 - .

_test_unstructured_client/unit/test_ndjson_elements_file.py

@@ -118,22 +118,38 @@ def test_mixed_chunk_formats(tmp_path):
 
 
 @pytest.mark.parametrize("body", ["", "   ", "\n\n"])
-def test_empty_chunk_files_are_skipped(tmp_path, body):
+def test_empty_chunk_files_raise(tmp_path, body):
+    """An empty 200 body must fail, not be skipped.
+
+    Skipping it made the document silently short: this function returns only a path and an
+    element count, so nothing downstream could tell a truncated document from a complete
+    one. `split_pdf_allow_failed` does not cover it either -- the chunk reported success.
+    """
     chunk_a = tmp_path / "a.json"
     chunk_empty = tmp_path / "empty.json"
-    elements_a = _elements("a", 2)
-    _write_json_array(chunk_a, elements_a)
+    _write_json_array(chunk_a, _elements("a", 2))
     chunk_empty.write_text(body, encoding="utf-8")
 
     out = tmp_path / "combined.ndjson"
-    written = combine_chunk_files_to_ndjson([str(chunk_a), str(chunk_empty)], str(out))
+    with pytest.raises(request_utils.EmptyChunkResponseError, match="empty.json"):
+        combine_chunk_files_to_ndjson([str(chunk_a), str(chunk_empty)], str(out))
+
 
-    assert written == 2
-    assert _read_ndjson(out) == elements_a
+def test_empty_chunk_error_is_a_value_error(tmp_path):
+    """Parity with the buffered path, which raises `JSONDecodeError` (a `ValueError`)."""
+    chunk_empty = tmp_path / "empty.json"
+    chunk_empty.write_text("", encoding="utf-8")
+
+    with pytest.raises(ValueError):
+        combine_chunk_files_to_ndjson([str(chunk_empty)], str(tmp_path / "combined.ndjson"))
 
 
 def test_empty_array_chunk_contributes_nothing(tmp_path):
-    """A chunk that legitimately produced no elements (e.g. blank pages)."""
+    """A chunk that legitimately produced no elements (e.g. blank pages).
+
+    The counterpart to `test_empty_chunk_files_raise`: `[]` and an empty body are
+    different responses on the wire, and only the latter is a defect.
+    """
     chunk_a = tmp_path / "a.json"
     chunk_b = tmp_path / "b.json"
     _write_json_array(chunk_a, [])
@@ -546,6 +562,29 @@ def test_malformed_chunk_leaves_no_partial_output_behind(tmp_path):
     assert list(Path(tmp_path).glob("*.partial")) == []
 
 
+def test_empty_chunk_response_fails_the_operation(tmp_path):
+    """An empty 200 chunk must fail the whole partition, as the buffered path does.
+
+    Driven through the hook because that is where the consequence lives: previously the
+    chunk was skipped and `_build_after_success_response` handed back a combined file that
+    was short by those pages, with a 200 alongside it. Also asserts no partial or spilled
+    file survives, since the raise happens mid-recombination.
+    """
+    operation_id = "op-empty-chunk"
+    hook = _hook_in_ndjson_mode(operation_id, tmp_path)
+    responses = [
+        (0, _ndjson_response(_elements("a", 2))),
+        (1, httpx.Response(status_code=200, content=b"")),
+    ]
+
+    with pytest.raises(request_utils.EmptyChunkResponseError):
+        hook._elements_from_task_responses(operation_id, responses, started_at=0.0)
+
+    assert operation_id not in hook.ndjson_output_path
+    assert _ndjson_files_in(tmp_path) == []
+    assert list(Path(tmp_path).glob("*.partial")) == []
+
+
 def test_no_combined_file_is_created_when_every_chunk_failed(tmp_path):
     operation_id = "op-all-failed"
     hook = _hook_in_ndjson_mode(operation_id, tmp_path)

src/unstructured_client/_hooks/custom/request_utils.py

@@ -290,6 +290,19 @@ def create_response(elements: list) -> httpx.Response:
 _SNIFF_BLOCK_SIZE = 64
 
 
+class EmptyChunkResponseError(ValueError):
+    """A split-PDF chunk returned HTTP 200 with a body that holds no elements at all.
+
+    An empty body is not the same wire response as an empty JSON array: `[]` is a chunk
+    that legitimately produced no elements (blank pages) and is accepted, while nothing
+    at all is a defect. Skipping it would make the document silently short, and
+    `split_pdf_allow_failed` cannot catch it because the chunk reports success.
+
+    Subclasses `ValueError` so that it lands where the buffered path's `JSONDecodeError`
+    (also a `ValueError`) already does for callers that guard the parse.
+    """
+
+
 def _first_non_space_char(stream: TextIO) -> str:
     """Return the first non-whitespace character in `stream`, or "" if there is none."""
     while True:
@@ -322,21 +335,31 @@ def combine_chunk_files_to_ndjson(chunk_paths: list[str], out_path: str) -> int:
 
     Returns:
         The number of elements written.
+
+    Raises:
+        EmptyChunkResponseError: A chunk returned 200 with an empty body.
     """
     total = 0
     with open(out_path, "w", encoding="utf-8") as out:
         for chunk_path in chunk_paths:
             with open(chunk_path, "r", encoding="utf-8") as chunk:
                 first_char = _first_non_space_char(chunk)
                 if not first_char:
-                    # A 200 with an empty body. Log it, because otherwise the document is
-                    # silently short and the element count cannot be reconciled against
-                    # the chunk count.
-                    logger.warning(
+                    # A 200 with an empty body. Fail loudly: skipping it makes the document
+                    # silently short with no way for the caller to notice, since this
+                    # function's only output is the combined path. The buffered path raises
+                    # `JSONDecodeError` on the same response, so NDJSON mode must not turn
+                    # a hard failure into truncation.
+                    logger.error(
                         "split_pdf event=ndjson_empty_chunk file=%s",
                         os.path.basename(chunk_path),
                     )
-                    continue
+                    raise EmptyChunkResponseError(
+                        "A split-PDF chunk returned HTTP 200 with an empty body "
+                        f"({os.path.basename(chunk_path)}); its elements would be missing "
+                        "from the combined output. An empty result must be an empty JSON "
+                        "array."
+                    )
                 chunk.seek(0)
 
                 if first_char == "[":

src/unstructured_client/_version.py

@@ -3,10 +3,10 @@
 import importlib.metadata
 
 __title__: str = "unstructured-client"
-__version__: str = "0.46.0"
+__version__: str = "0.46.1"
 __openapi_doc_version__: str = "1.2.31"
 __gen_version__: str = "2.680.0"
-__user_agent__: str = "speakeasy-sdk/python 0.46.0 2.680.0 1.2.31 unstructured-client"
+__user_agent__: str = "speakeasy-sdk/python 0.46.1 2.680.0 1.2.31 unstructured-client"
 
 try:
     if __package__ is not None: