Throw descriptive error when sandbox is killed mid-request (#291)

* Throw descriptive error when sandbox is killed mid-request

When the sandbox is killed or times out while a request to the Jupyter
server is in flight (runCode/run_code or context management), the SDKs
surfaced a raw socket error (e.g. ECONNRESET). Now they detect the
closed connection, confirm the sandbox is gone via its health check,
and throw a descriptive SandboxError/SandboxException instead. If the
sandbox is still running (or its state can't be determined), the
original error propagates unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix Prettier formatting of e2b import

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Use TimeoutError for confirmed sandbox-killed errors

Matches the existing 502 mapping in extractError/extract_exception and
the base SDK convention: a dead sandbox surfaces as TimeoutError /
TimeoutException. When the health probe is inconclusive or the sandbox
is still running, the original transport error propagates unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Merge sandbox-killed check and request timeout formatting

Consolidate the two-line catch handler into a single
formatRequestError call that returns the error to throw, matching
the main SDK pattern (e2b-dev/E2B#1419).

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

* Rename error handlers to match main SDK conventions

Align with e2b-dev/E2B#1419, which names the health-check-aware
error wrappers handle*Error / handle_*_exception:
- JS: formatRequestError -> handleRequestError
- Python: _raise_if_sandbox_killed -> _handle_connection_error

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

* Keep killed-sandbox tests in-flight until the kill

The kill-during-execution tests used time.sleep(60), which in JS
matched the default execution timeout (DEFAULT_TIMEOUT_MS = 60s). A
slow kill could let the body-timer abort (or the sleep completing)
end the request instead of the connection reset, masking the
sandbox-killed path the test asserts.

Bump the sleep to 300s and set an explicit execution timeout well
beyond the kill + disconnect-detection window so the sandbox kill is
the only thing that ends the request, matching the interrupt test's
convention. Add a 60s vitest timeout to the JS test for the
disconnect-detection window.

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: mishushakov

.changeset/grumpy-sloths-relax.md

@@ -0,0 +1,6 @@
+---
+'@e2b/code-interpreter': patch
+'@e2b/code-interpreter-python': patch
+---
+
+Throw a descriptive `TimeoutError`/`TimeoutException` instead of a raw socket error (e.g. `ECONNRESET`) when the sandbox is killed or times out while a request (`runCode`/`run_code`, context management) is in progress

js/src/sandbox.ts

@@ -1,4 +1,4 @@
-import { Sandbox as BaseSandbox, InvalidArgumentError } from 'e2b'
+import { Sandbox as BaseSandbox, InvalidArgumentError, TimeoutError } from 'e2b'
 
 import {
   Result,
@@ -11,6 +11,7 @@ import {
 import {
   formatExecutionTimeoutError,
   formatRequestTimeoutError,
+  isConnectionClosedError,
   readLines,
 } from './utils'
 import { JUPYTER_PORT, DEFAULT_TIMEOUT_MS } from './consts'
@@ -278,7 +279,7 @@ export class Sandbox extends BaseSandbox {
 
       return execution
     } catch (error) {
-      throw formatRequestTimeoutError(error)
+      throw await this.handleRequestError(error)
     }
   }
 
@@ -317,7 +318,7 @@ export class Sandbox extends BaseSandbox {
 
       return await res.json()
     } catch (error) {
-      throw formatRequestTimeoutError(error)
+      throw await this.handleRequestError(error)
     }
   }
 
@@ -353,7 +354,7 @@ export class Sandbox extends BaseSandbox {
         throw error
       }
     } catch (error) {
-      throw formatRequestTimeoutError(error)
+      throw await this.handleRequestError(error)
     }
   }
 
@@ -388,7 +389,7 @@ export class Sandbox extends BaseSandbox {
 
       return await res.json()
     } catch (error) {
-      throw formatRequestTimeoutError(error)
+      throw await this.handleRequestError(error)
     }
   }
 
@@ -424,7 +425,30 @@ export class Sandbox extends BaseSandbox {
         throw error
       }
     } catch (error) {
-      throw formatRequestTimeoutError(error)
+      throw await this.handleRequestError(error)
     }
   }
+
+  /**
+   * Returns the error to throw for a failed request. If the connection was
+   * closed because the sandbox was killed mid-request, returns a descriptive
+   * `TimeoutError`. Otherwise falls back to formatting request timeouts and
+   * re-throwing the original error.
+   */
+  private async handleRequestError(error: unknown): Promise<unknown> {
+    if (
+      isConnectionClosedError(error) &&
+      // If the state check itself fails we can't tell whether the sandbox
+      // was killed — assume it's running so we re-throw the original error
+      // instead of wrongly claiming the sandbox is gone.
+      (await this.isRunning().catch(() => true)) === false
+    ) {
+      return new TimeoutError(
+        'The sandbox was killed while the request was in progress. This can happen when the sandbox times out or is killed manually. ' +
+          "You can modify the sandbox timeout by passing 'timeoutMs' when starting the sandbox or calling '.setTimeout' on the sandbox with the desired timeout."
+      )
+    }
+
+    return formatRequestTimeoutError(error)
+  }
 }

js/src/utils.ts

@@ -20,6 +20,35 @@ export function formatExecutionTimeoutError(error: unknown) {
   return error
 }
 
+const CONNECTION_CLOSED_CODES = ['ECONNRESET', 'EPIPE', 'UND_ERR_SOCKET']
+
+/**
+ * Checks if the error means the connection was closed/reset while the request
+ * was in flight. The shape of this error is runtime-specific — Bun and Deno
+ * set a `code` directly, while Node's fetch (undici) wraps the socket error
+ * in the `cause` of a generic `TypeError`.
+ */
+export function isConnectionClosedError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false
+  }
+
+  const code = (error as { code?: unknown }).code
+  if (typeof code === 'string' && CONNECTION_CLOSED_CODES.includes(code)) {
+    return true
+  }
+
+  if (error.name === 'ConnectionReset' || error.name === 'ConnectionClosed') {
+    return true
+  }
+
+  if (error.cause) {
+    return isConnectionClosedError(error.cause)
+  }
+
+  return false
+}
+
 export async function* readLines(stream: ReadableStream<Uint8Array>) {
   const reader = stream.getReader()
   let buffer = ''

js/tests/killedSandbox.test.ts

@@ -0,0 +1,30 @@
+import { TimeoutError } from 'e2b'
+import { expect } from 'vitest'
+
+import { isDebug, sandboxTest, wait } from './setup'
+
+sandboxTest.skipIf(isDebug)(
+  'runCode throws a descriptive error when the sandbox is killed during execution',
+  async ({ sandbox }) => {
+    // Keep the execution firmly in-flight until the kill: the sleep is far
+    // longer than the kill delay and the execution timeout is pushed well
+    // beyond the kill + disconnect-detection window, so the only thing that
+    // ends the request is the sandbox being killed (not a body-timer abort
+    // or the sleep completing on its own).
+    const execution = sandbox.runCode('import time; time.sleep(300)', {
+      timeoutMs: 300_000,
+    })
+    const assertion = Promise.all([
+      expect(execution).rejects.toThrowError(
+        /sandbox was killed while the request was in progress/
+      ),
+      expect(execution).rejects.toBeInstanceOf(TimeoutError),
+    ])
+
+    await wait(2_000)
+    await sandbox.kill()
+
+    await assertion
+  },
+  60_000
+)

python/e2b_code_interpreter/code_interpreter_async.py

@@ -29,6 +29,7 @@
 from e2b_code_interpreter.exceptions import (
     format_execution_timeout_error,
     format_request_timeout_error,
+    format_sandbox_killed_error,
 )
 
 logger = logging.getLogger(__name__)
@@ -83,6 +84,23 @@ def _client(self) -> AsyncClient:
             transport=get_transport(self.connection_config, http2=False),
         )
 
+    async def _handle_connection_error(self, err: Exception) -> None:
+        """
+        Raises a descriptive exception if the connection error was caused by
+        the sandbox being killed mid-request. If the sandbox is still running
+        (or its state can't be determined), returns so the caller can re-raise
+        the original error.
+        """
+        try:
+            running = await self.is_running()
+        except Exception:
+            # The state check itself failed, so we can't tell whether the
+            # sandbox was killed — let the caller re-raise the original error
+            # instead of wrongly claiming the sandbox is gone.
+            return
+        if not running:
+            raise format_sandbox_killed_error() from err
+
     @overload
     async def run_code(
         self,
@@ -217,6 +235,9 @@ async def run_code(
             raise format_execution_timeout_error()
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            await self._handle_connection_error(err)
+            raise
 
     async def create_code_context(
         self,
@@ -263,6 +284,9 @@ async def create_code_context(
             return Context.from_json(data)
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            await self._handle_connection_error(err)
+            raise
 
     async def remove_code_context(
         self,
@@ -295,6 +319,9 @@ async def remove_code_context(
                 raise err
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            await self._handle_connection_error(err)
+            raise
 
     async def list_code_contexts(self) -> List[Context]:
         """
@@ -323,6 +350,9 @@ async def list_code_contexts(self) -> List[Context]:
             return [Context.from_json(context_data) for context_data in data]
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            await self._handle_connection_error(err)
+            raise
 
     async def restart_code_context(
         self,
@@ -354,3 +384,6 @@ async def restart_code_context(
                 raise err
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            await self._handle_connection_error(err)
+            raise

python/e2b_code_interpreter/code_interpreter_sync.py

@@ -25,6 +25,7 @@
 from e2b_code_interpreter.exceptions import (
     format_execution_timeout_error,
     format_request_timeout_error,
+    format_sandbox_killed_error,
 )
 
 logger = logging.getLogger(__name__)
@@ -77,6 +78,23 @@ def _client(self) -> Client:
         # cancelled reliably.
         return Client(transport=get_transport(self.connection_config, http2=False))
 
+    def _handle_connection_error(self, err: Exception) -> None:
+        """
+        Raises a descriptive exception if the connection error was caused by
+        the sandbox being killed mid-request. If the sandbox is still running
+        (or its state can't be determined), returns so the caller can re-raise
+        the original error.
+        """
+        try:
+            running = self.is_running()
+        except Exception:
+            # The state check itself failed, so we can't tell whether the
+            # sandbox was killed — let the caller re-raise the original error
+            # instead of wrongly claiming the sandbox is gone.
+            return
+        if not running:
+            raise format_sandbox_killed_error() from err
+
     @overload
     def run_code(
         self,
@@ -210,6 +228,9 @@ def run_code(
             raise format_execution_timeout_error()
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            self._handle_connection_error(err)
+            raise
 
     def create_code_context(
         self,
@@ -256,6 +277,9 @@ def create_code_context(
             return Context.from_json(data)
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            self._handle_connection_error(err)
+            raise
 
     def remove_code_context(
         self,
@@ -288,6 +312,9 @@ def remove_code_context(
                 raise err
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            self._handle_connection_error(err)
+            raise
 
     def list_code_contexts(self) -> List[Context]:
         """
@@ -316,6 +343,9 @@ def list_code_contexts(self) -> List[Context]:
             return [Context.from_json(context_data) for context_data in data]
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            self._handle_connection_error(err)
+            raise
 
     def restart_code_context(
         self,
@@ -348,3 +378,6 @@ def restart_code_context(
                 raise err
         except httpx.TimeoutException:
             raise format_request_timeout_error()
+        except (httpx.ReadError, httpx.RemoteProtocolError) as err:
+            self._handle_connection_error(err)
+            raise

python/e2b_code_interpreter/exceptions.py

@@ -11,3 +11,10 @@ def format_execution_timeout_error() -> Exception:
     return TimeoutException(
         "Execution timed out — the 'timeout' option can be used to increase this timeout",
     )
+
+
+def format_sandbox_killed_error() -> Exception:
+    return TimeoutException(
+        "The sandbox was killed while the request was in progress. This can happen when the sandbox times out or is killed manually. "
+        "You can modify the sandbox timeout by passing 'timeout' when starting the sandbox or calling '.set_timeout' on the sandbox with the desired timeout",
+    )

python/tests/async/test_async_killed.py

@@ -0,0 +1,27 @@
+import asyncio
+
+import pytest
+
+from e2b import TimeoutException
+from e2b_code_interpreter import AsyncSandbox
+
+
+@pytest.mark.skip_debug
+async def test_run_code_raises_when_sandbox_is_killed_during_execution(
+    async_sandbox: AsyncSandbox,
+):
+    # Keep the execution firmly in-flight until the kill: the sleep is far
+    # longer than the kill delay and the execution timeout is well beyond the
+    # kill + disconnect-detection window, so the only thing that ends the
+    # request is the sandbox being killed.
+    execution = asyncio.create_task(
+        async_sandbox.run_code("import time; time.sleep(300)", timeout=300)
+    )
+
+    await asyncio.sleep(2)
+    await async_sandbox.kill()
+
+    with pytest.raises(
+        TimeoutException, match="sandbox was killed while the request was in progress"
+    ):
+        await execution

python/tests/sync/test_killed.py

@@ -0,0 +1,25 @@
+import threading
+
+import pytest
+
+from e2b import TimeoutException
+from e2b_code_interpreter import Sandbox
+
+
+@pytest.mark.skip_debug
+def test_run_code_raises_when_sandbox_is_killed_during_execution(sandbox: Sandbox):
+    timer = threading.Timer(2.0, sandbox.kill)
+    timer.start()
+
+    try:
+        with pytest.raises(
+            TimeoutException,
+            match="sandbox was killed while the request was in progress",
+        ):
+            # Keep the execution firmly in-flight until the kill: the sleep is
+            # far longer than the kill delay and the execution timeout is well
+            # beyond the kill + disconnect-detection window, so the only thing
+            # that ends the request is the sandbox being killed.
+            sandbox.run_code("import time; time.sleep(300)", timeout=300)
+    finally:
+        timer.cancel()