fix(transfer): structured envelope on connection errors (BE-2454)

comfy download / comfy upload wrapped their HTTP calls in
`except urllib.error.HTTPError` only. HTTPError is a subclass of
URLError, so a connection-level failure — connection refused, DNS
failure, timeout, TLS error, or a reset mid-transfer — raised the parent
URLError, a bare TimeoutError, or a bare ConnectionError and escaped as
an unhandled traceback, breaking --json / NDJSON consumers that expect a
structured error envelope.

Add a second except arm at both call sites (execute_download and
execute_upload) catching (URLError, TimeoutError, ConnectionError) and
emitting the existing download_failed / upload_failed envelope with the
underlying reason in details. HTTPError stays first for its
status-specific message; ConnectionError covers a mid-stream reset
without swallowing disk-write OSErrors.

Signed-off-by: Alexander Piskun <bigcat88@icloud.com>

Author: bigcat88

comfy_cli/command/transfer.py

@@ -283,6 +283,20 @@ def execute_upload(
                 details={"status": status, "filename": filename},
             )
             raise typer.Exit(code=1)
+        except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+            # A connection-level failure (refused / DNS / timeout / TLS at
+            # connect, or a reset / read-timeout mid-transfer) raises URLError,
+            # a bare TimeoutError, or a bare ConnectionError — never HTTPError.
+            # Surface it as a structured envelope instead of letting an
+            # unhandled traceback break machine/NDJSON consumers.
+            reason = getattr(e, "reason", None) or e
+            renderer.error(
+                code="upload_failed",
+                message=f"Failed to upload {filename}: {reason}",
+                hint="check that the server is reachable",
+                details={"filename": filename, "reason": str(reason)},
+            )
+            raise typer.Exit(code=1)
 
         cloud_name = result.get("name", filename)
         subfolder = result.get("subfolder", "")
@@ -516,6 +530,20 @@ def execute_download(
                 details={"status": e.code, "url": url, "index": idx},
             )
             raise typer.Exit(code=1)
+        except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+            # A connection-level failure (refused / DNS / timeout / TLS at
+            # connect, or a reset / read-timeout mid-transfer) raises URLError,
+            # a bare TimeoutError, or a bare ConnectionError — never HTTPError.
+            # Surface it as a structured envelope instead of letting an
+            # unhandled traceback break machine/NDJSON consumers.
+            reason = getattr(e, "reason", None) or e
+            renderer.error(
+                code="download_failed",
+                message=f"Failed to download output {idx}: {reason}",
+                hint="check that the server is reachable and the output URL is correct",
+                details={"url": url, "index": idx, "reason": str(reason)},
+            )
+            raise typer.Exit(code=1)
 
         file_size = local_path.stat().st_size
         entry: dict[str, Any] = {

tests/comfy_cli/command/test_transfer_download.py

@@ -10,10 +10,12 @@
 from __future__ import annotations
 
 import json
+import urllib.error
 from pathlib import Path
 from unittest.mock import patch
 
 import pytest
+import typer
 
 from comfy_cli import comfy_client, jobs_state
 from comfy_cli.comfy_client import extract_output_entries
@@ -378,6 +380,74 @@ def test_ndjson_mode_emits_no_human_progress_line(self, fake_target, tmp_path, c
         assert "downloaded" not in captured.err
 
 
+class TestDownloadConnectionError:
+    """A connection-level failure — server unreachable, DNS failure, read
+    timeout, TLS error — raises the parent ``URLError`` (or a bare
+    ``TimeoutError`` on a read timeout), not ``HTTPError``. It must surface as a
+    structured ``download_failed`` envelope with stdout staying pure JSON, never
+    an unhandled traceback that breaks ``--json``/NDJSON consumers (BE-2454)."""
+
+    def _run(self, fake_target, tmp_path, side_effect) -> typer.Exit:
+        with (
+            patch("comfy_cli.command.transfer.resolve_target", return_value=fake_target),
+            patch.object(transfer._DOWNLOAD_OPENER, "open", side_effect=side_effect),
+        ):
+            with pytest.raises(typer.Exit) as excinfo:
+                transfer.execute_download(PROMPT_ID, out_dir=str(tmp_path / "out"))
+        return excinfo.value
+
+    def test_urlerror_emits_download_failed_envelope(self, fake_target, tmp_path, capsys):
+        _write_state(fake_target)
+        set_renderer(Renderer(mode=OutputMode.JSON, command="download"))
+
+        def _refused(req):
+            raise urllib.error.URLError(ConnectionRefusedError(111, "Connection refused"))
+
+        exc = self._run(fake_target, tmp_path, _refused)
+
+        assert exc.exit_code == 1
+        out_lines = [ln for ln in capsys.readouterr().out.splitlines() if ln.strip()]
+        env = json.loads(out_lines[-1])
+        assert env["ok"] is False
+        assert env["error"]["code"] == "download_failed"
+        assert "Connection refused" in env["error"]["message"]
+        assert "Connection refused" in env["error"]["details"]["reason"]
+
+    def test_bare_timeout_is_also_caught(self, fake_target, tmp_path, capsys):
+        _write_state(fake_target)
+        set_renderer(Renderer(mode=OutputMode.JSON, command="download"))
+
+        def _timeout(req):
+            raise TimeoutError("timed out")
+
+        exc = self._run(fake_target, tmp_path, _timeout)
+
+        assert exc.exit_code == 1
+        env = json.loads([ln for ln in capsys.readouterr().out.splitlines() if ln.strip()][-1])
+        assert env["error"]["code"] == "download_failed"
+
+    def test_connection_reset_mid_stream_is_caught(self, fake_target, tmp_path, capsys):
+        _write_state(fake_target)
+        set_renderer(Renderer(mode=OutputMode.JSON, command="download"))
+
+        class _ResetResp:
+            def read(self, n):
+                raise ConnectionResetError(104, "Connection reset by peer")
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc):
+                return False
+
+        exc = self._run(fake_target, tmp_path, lambda req: _ResetResp())
+
+        assert exc.exit_code == 1
+        env = json.loads([ln for ln in capsys.readouterr().out.splitlines() if ln.strip()][-1])
+        assert env["error"]["code"] == "download_failed"
+        assert "reset by peer" in env["error"]["message"]
+
+
 # ---------------------------------------------------------------------------
 # _default_out_dir — project/1 root wins over the legacy config key
 # ---------------------------------------------------------------------------

tests/comfy_cli/command/test_transfer_upload.py

@@ -14,6 +14,7 @@
 from pathlib import Path
 
 import pytest
+import typer
 
 from comfy_cli.command import transfer
 from comfy_cli.target import Target
@@ -145,3 +146,36 @@ def test_json_mode_stdout_is_pure_json_no_human_line(self, asset, monkeypatch, c
         assert parsed[-1]["data"]["uploads"][0]["cloud_name"] == "ab12.png"
         assert "uploaded" not in captured.out
         assert "uploaded" not in captured.err
+
+
+class TestUploadConnectionError:
+    """A connection-level failure (``URLError``/``TimeoutError``) on upload must
+    surface as a structured ``upload_failed`` envelope, not an unhandled
+    traceback that breaks ``--json``/NDJSON consumers (BE-2454)."""
+
+    @pytest.fixture(autouse=True)
+    def reset_renderer(self):
+        from comfy_cli.output.renderer import reset_renderer_for_testing
+
+        reset_renderer_for_testing()
+        yield
+        reset_renderer_for_testing()
+
+    def test_urlerror_emits_upload_failed_envelope(self, asset, monkeypatch, capsys):
+        from comfy_cli.output import Renderer, set_renderer
+        from comfy_cli.output.renderer import OutputMode
+
+        err = urllib.error.URLError(ConnectionRefusedError(111, "Connection refused"))
+        monkeypatch.setattr(transfer, "_TRANSFER_OPENER", _FakeOpener(error=err))
+        monkeypatch.setattr(transfer, "resolve_target", lambda where=None: _local_target())
+        set_renderer(Renderer(mode=OutputMode.JSON, command="upload"))
+
+        with pytest.raises(typer.Exit) as excinfo:
+            transfer.execute_upload([str(asset)], where="local")
+
+        assert excinfo.value.exit_code == 1
+        env = json.loads([ln for ln in capsys.readouterr().out.splitlines() if ln.strip()][-1])
+        assert env["ok"] is False
+        assert env["error"]["code"] == "upload_failed"
+        assert "Connection refused" in env["error"]["message"]
+        assert "Connection refused" in env["error"]["details"]["reason"]