Improve session initialization to check storage first (#281)

* Improve session initialization to check storage first

Reduces unnecessary "session already exists" errors by checking
DO storage before attempting to create a new session.

* Add changeset for session initialization fix

* Remove redundant storage check from session initialization

The storage check was defensive code that added latency but rarely
helped since the constructor already loads defaultSession from storage
via blockConcurrencyWhile.

* Use RESOURCE_BUSY error code for session conflicts

Changes INTERNAL_ERROR (500) to RESOURCE_BUSY (409) for "session
already exists" errors. This prevents noisy ERROR-level logs during
wrangler dev hot reloads since the SDK only logs 5xx errors.

Also improves the debug message to clarify state divergence.

* Use error code instead of string matching for session conflicts

String matching on error.message is fragile - if the message wording
changes, the code silently breaks. Using error.code is type-safe and
reliable.

* Add SESSION_ALREADY_EXISTS error code for session conflicts

Replaces RESOURCE_BUSY with a semantically correct error code that
properly indicates a uniqueness constraint violation rather than a
temporary lock.

Author: ghostwriternr

.changeset/improve-session-initialization.md

@@ -0,0 +1,5 @@
+---
+'@cloudflare/sandbox': patch
+---
+
+Fix session initialization to eliminate noisy error logs during hot reloads

CLAUDE.md

@@ -291,6 +291,10 @@ Turbo handles task orchestration (`turbo.json`) with dependency-aware builds.
 
 **Subject line should stand alone** - don't require reading the body to understand the change. Body is optional and only needed for non-obvious context.
 
+**Focus on the change, not how it was discovered** - never reference "review feedback", "PR comments", or "code review" in commit messages. Describe what the change does and why, not that someone asked for it.
+
+**Avoid bullet points** - write prose, not lists. If you need bullets to explain a change, you're either committing too much at once or over-explaining implementation details. The body should be a brief paragraph, not a changelog.
+
 Good examples:
 
 ```

packages/sandbox-container/src/services/session-manager.ts

@@ -32,11 +32,10 @@ export class SessionManager {
           success: false,
           error: {
             message: `Session '${options.id}' already exists`,
-            code: ErrorCode.INTERNAL_ERROR,
+            code: ErrorCode.SESSION_ALREADY_EXISTS,
             details: {
-              sessionId: options.id,
-              originalError: 'Session already exists'
-            } satisfies InternalErrorContext
+              sessionId: options.id
+            }
           }
         };
       }

packages/sandbox/src/errors/adapter.ts

@@ -26,6 +26,7 @@ import type {
   PortNotExposedContext,
   ProcessErrorContext,
   ProcessNotFoundContext,
+  SessionAlreadyExistsContext,
   ValidationFailedContext
 } from '@repo/shared/errors';
 import { ErrorCode } from '@repo/shared/errors';
@@ -58,6 +59,7 @@ import {
   ProcessNotFoundError,
   SandboxError,
   ServiceNotRespondingError,
+  SessionAlreadyExistsError,
   ValidationFailedError
 } from './classes';
 
@@ -123,6 +125,12 @@ export function createErrorFromResponse(errorResponse: ErrorResponse): Error {
         errorResponse as unknown as ErrorResponse<ProcessErrorContext>
       );
 
+    // Session Errors
+    case ErrorCode.SESSION_ALREADY_EXISTS:
+      return new SessionAlreadyExistsError(
+        errorResponse as unknown as ErrorResponse<SessionAlreadyExistsContext>
+      );
+
     // Port Errors
     case ErrorCode.PORT_ALREADY_EXPOSED:
       return new PortAlreadyExposedError(

packages/sandbox/src/errors/classes.ts

@@ -28,6 +28,7 @@ import type {
   ProcessExitedBeforeReadyContext,
   ProcessNotFoundContext,
   ProcessReadyTimeoutContext,
+  SessionAlreadyExistsContext,
   ValidationFailedContext
 } from '@repo/shared/errors';
 
@@ -236,6 +237,25 @@ export class ProcessError extends SandboxError<ProcessErrorContext> {
   }
 }
 
+// ============================================================================
+// Session Errors
+// ============================================================================
+
+/**
+ * Error thrown when a session already exists
+ */
+export class SessionAlreadyExistsError extends SandboxError<SessionAlreadyExistsContext> {
+  constructor(errorResponse: ErrorResponse<SessionAlreadyExistsContext>) {
+    super(errorResponse);
+    this.name = 'SessionAlreadyExistsError';
+  }
+
+  // Type-safe accessors
+  get sessionId() {
+    return this.context.sessionId;
+  }
+}
+
 // ============================================================================
 // Port Errors
 // ============================================================================

packages/sandbox/src/errors/index.ts

@@ -109,6 +109,8 @@ export {
   ProcessReadyTimeoutError,
   SandboxError,
   ServiceNotRespondingError,
+  // Session Errors
+  SessionAlreadyExistsError,
   // Validation Errors
   ValidationFailedError
 } from './classes';

packages/sandbox/src/sandbox.ts

@@ -37,7 +37,8 @@ import {
   CustomDomainRequiredError,
   ErrorCode,
   ProcessExitedBeforeReadyError,
-  ProcessReadyTimeoutError
+  ProcessReadyTimeoutError,
+  SessionAlreadyExistsError
 } from './errors';
 import { CodeInterpreter } from './interpreter';
 import { isLocalhostPattern } from './request-handler';
@@ -994,39 +995,38 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
    * we reuse it instead of trying to create a new one.
    */
   private async ensureDefaultSession(): Promise<string> {
-    if (!this.defaultSession) {
-      const sessionId = `sandbox-${this.sandboxName || 'default'}`;
+    const sessionId = `sandbox-${this.sandboxName || 'default'}`;
 
-      try {
-        // Try to create session in container
-        await this.client.utils.createSession({
-          id: sessionId,
-          env: this.envVars || {},
-          cwd: '/workspace'
-        });
+    // Fast path: session already initialized in this instance
+    if (this.defaultSession === sessionId) {
+      return this.defaultSession;
+    }
+
+    // Create session in container
+    try {
+      await this.client.utils.createSession({
+        id: sessionId,
+        env: this.envVars || {},
+        cwd: '/workspace'
+      });
 
+      this.defaultSession = sessionId;
+      await this.ctx.storage.put('defaultSession', sessionId);
+      this.logger.debug('Default session initialized', { sessionId });
+    } catch (error: unknown) {
+      // Session may already exist (e.g., after hot reload or concurrent request)
+      if (error instanceof SessionAlreadyExistsError) {
+        this.logger.debug(
+          'Session exists in container but not in DO state, syncing',
+          { sessionId }
+        );
         this.defaultSession = sessionId;
-        // Persist to storage so it survives hot reloads
         await this.ctx.storage.put('defaultSession', sessionId);
-        this.logger.debug('Default session initialized', { sessionId });
-      } catch (error: unknown) {
-        // If session already exists (e.g., after hot reload), reuse it
-        if (
-          error instanceof Error &&
-          error.message.includes('already exists')
-        ) {
-          this.logger.debug('Reusing existing session after reload', {
-            sessionId
-          });
-          this.defaultSession = sessionId;
-          // Persist to storage in case it wasn't saved before
-          await this.ctx.storage.put('defaultSession', sessionId);
-        } else {
-          // Re-throw other errors
-          throw error;
-        }
+      } else {
+        throw error;
       }
     }
+
     return this.defaultSession;
   }
 

packages/shared/src/errors/codes.ts

@@ -43,6 +43,9 @@ export const ErrorCode = {
   PROCESS_PERMISSION_DENIED: 'PROCESS_PERMISSION_DENIED',
   PROCESS_ERROR: 'PROCESS_ERROR',
 
+  // Session Errors (409)
+  SESSION_ALREADY_EXISTS: 'SESSION_ALREADY_EXISTS',
+
   // Port Errors (409)
   PORT_ALREADY_EXPOSED: 'PORT_ALREADY_EXPOSED',
   PORT_IN_USE: 'PORT_IN_USE',

packages/shared/src/errors/contexts.ts

@@ -48,6 +48,10 @@ export interface ProcessErrorContext {
   stderr?: string;
 }
 
+export interface SessionAlreadyExistsContext {
+  sessionId: string;
+}
+
 /**
  * Process readiness error contexts
  */

packages/shared/src/errors/index.ts

@@ -57,6 +57,7 @@ export type {
   ProcessExitedBeforeReadyContext,
   ProcessNotFoundContext,
   ProcessReadyTimeoutContext,
+  SessionAlreadyExistsContext,
   ValidationFailedContext
 } from './contexts';
 // Export utility functions