Wrap ClientConfig environment reads with explicit error context

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

hyperbrowser/config.py

@@ -305,7 +305,7 @@ def normalize_base_url(base_url: str) -> str:
 
     @classmethod
     def from_env(cls) -> "ClientConfig":
-        api_key = os.environ.get("HYPERBROWSER_API_KEY")
+        api_key = cls._read_env_value("HYPERBROWSER_API_KEY")
         if api_key is None:
             raise HyperbrowserError(
                 "HYPERBROWSER_API_KEY environment variable is required"
@@ -316,11 +316,23 @@ def from_env(cls) -> "ClientConfig":
         )
 
         base_url = cls.resolve_base_url_from_env(
-            os.environ.get("HYPERBROWSER_BASE_URL")
+            cls._read_env_value("HYPERBROWSER_BASE_URL")
         )
-        headers = cls.parse_headers_from_env(os.environ.get("HYPERBROWSER_HEADERS"))
+        headers = cls.parse_headers_from_env(cls._read_env_value("HYPERBROWSER_HEADERS"))
         return cls(api_key=api_key, base_url=base_url, headers=headers)
 
+    @staticmethod
+    def _read_env_value(env_name: str) -> Optional[str]:
+        try:
+            return os.environ.get(env_name)
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            raise HyperbrowserError(
+                f"Failed to read {env_name} environment variable",
+                original_error=exc,
+            ) from exc
+
     @staticmethod
     def parse_headers_from_env(raw_headers: Optional[str]) -> Optional[Dict[str, str]]:
         return parse_headers_env_json(raw_headers)

tests/test_config.py

@@ -33,6 +33,90 @@ def test_client_config_from_env_rejects_control_character_api_key(monkeypatch):
         ClientConfig.from_env()
 
 
+def test_client_config_from_env_wraps_api_key_env_read_runtime_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    original_get = config_module.os.environ.get
+
+    def _broken_get(env_name: str, default=None):
+        if env_name == "HYPERBROWSER_API_KEY":
+            raise RuntimeError("api key env read exploded")
+        return original_get(env_name, default)
+
+    monkeypatch.setattr(config_module.os.environ, "get", _broken_get)
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="api key env read exploded",
+    ) as exc_info:
+        ClientConfig.from_env()
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+def test_client_config_from_env_wraps_base_url_env_read_runtime_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    original_get = config_module.os.environ.get
+    monkeypatch.setenv("HYPERBROWSER_API_KEY", "test-key")
+
+    def _broken_get(env_name: str, default=None):
+        if env_name == "HYPERBROWSER_BASE_URL":
+            raise RuntimeError("base url env read exploded")
+        return original_get(env_name, default)
+
+    monkeypatch.setattr(config_module.os.environ, "get", _broken_get)
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="base url env read exploded",
+    ) as exc_info:
+        ClientConfig.from_env()
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+def test_client_config_from_env_wraps_headers_env_read_runtime_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    original_get = config_module.os.environ.get
+    monkeypatch.setenv("HYPERBROWSER_API_KEY", "test-key")
+    monkeypatch.setenv("HYPERBROWSER_BASE_URL", "https://api.hyperbrowser.ai")
+
+    def _broken_get(env_name: str, default=None):
+        if env_name == "HYPERBROWSER_HEADERS":
+            raise RuntimeError("headers env read exploded")
+        return original_get(env_name, default)
+
+    monkeypatch.setattr(config_module.os.environ, "get", _broken_get)
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="headers env read exploded",
+    ) as exc_info:
+        ClientConfig.from_env()
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+def test_client_config_from_env_preserves_hyperbrowser_env_read_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    def _broken_read_env(env_name: str):
+        if env_name == "HYPERBROWSER_API_KEY":
+            raise HyperbrowserError("custom env read failure")
+        return None
+
+    monkeypatch.setattr(
+        ClientConfig, "_read_env_value", staticmethod(_broken_read_env)
+    )
+
+    with pytest.raises(HyperbrowserError, match="custom env read failure") as exc_info:
+        ClientConfig.from_env()
+
+    assert exc_info.value.original_error is None
+
+
 def test_client_config_from_env_reads_api_key_and_base_url(monkeypatch):
     monkeypatch.setenv("HYPERBROWSER_API_KEY", "test-key")
     monkeypatch.setenv("HYPERBROWSER_BASE_URL", "https://example.local")