paperclipai/paperclip · error · Error

daytona_sandbox_not_found

daytona_sandbox_not_found

Error message

daytona_sandbox_not_found

What it means

When a Daytona sandbox provider operation fails because the sandbox no longer exists, the plugin catches DaytonaNotFoundError from the SDK and rethrows a plain Error with the stable message 'daytona_sandbox_not_found'. The comment explains that a deleted sandbox is the one provider failure proving the unexported workspace bytes are gone; converting the SDK class to a stable cross-worker message lets other workers treat it as non-retryable, while all other errors remain retryable.

Source

Thrown at packages/plugins/sandbox-providers/daytona/src/plugin.ts:2865

    try {
      return await withSandboxActivityGate(scope, async () => {
        const sandbox = await getSandbox(scope, { bypassTeardownGate: true });
        await ensureSandboxStarted(sandbox, timeoutSeconds);
        const result = await performSyncOut({
          sandbox,
          operations: params.operations,
          remoteDir,
          timeoutSeconds,
        });
        sandboxHandleCache.markFresh(scope);
        return result;
      });
    } catch (error) {
      // A deleted Daytona sandbox is the one provider failure that proves its
      // unexported workspace bytes no longer exist. Convert the SDK class to a
      // stable cross-worker message; every other error remains retryable.
      if (error instanceof DaytonaNotFoundError) {
        throw new Error("daytona_sandbox_not_found");
      }
      throw error;
    }
  },

  // Open one live login pseudo-terminal. Resolve the cached sandbox by the
  // provider lease id, revalidate the host launch descriptor, create the session
  // home with one `mkdir -p` command, run the fixed login command on a real
  // pseudo-terminal, and register the session under the host route id. Stream the
  // raw output and the exit through `ctx.loginPty`, bound to the returned worker
  // session id. Fail closed when no cached sandbox matches the lease.
  async onLoginPtyOpen(params) {
    const sandbox = await sandboxHandleCache.findByProviderLeaseId(params.providerLeaseId);
    if (!sandbox) {
      throw new Error(
        "Daytona login pseudo-terminal: no cached sandbox resolves the provider lease.",
      );
    }

View on GitHub (pinned to 01ad858492)

Solutions

  1. Treat the message 'daytona_sandbox_not_found' as terminal: stop retrying and recreate the sandbox/workspace from source instead of the deleted instance
  2. Export/snapshot workspace bytes before deletion so the work is recoverable after a not-found error
  3. Check the Daytona console/API for the sandbox ID to confirm deletion and whether a snapshot exists to restore from
  4. Align sandbox TTL/keep-alive settings with workload duration so long jobs are not orphaned
  5. Clear the cached sandbox reference in the plugin state and provision a fresh sandbox for the task

Example fix

// before (retry loop on all errors)
catch (e) { await retry(op); }
// after
try { await op(); } catch (e) {
  if (e.message === 'daytona_sandbox_not_found') return recreateSandboxAndRerun(); // terminal, do not retry
  await retry(op);
}
Defensive patterns

Strategy: fallback

Validate before calling

const exists = await daytonaClient.sandbox.get(sandboxId).then(() => true, e => !(e instanceof DaytonaNotFoundError)); if (!exists) provisionNewSandbox();

Type guard

function isSandboxNotFound(e: unknown) { return e instanceof Error && e.message === 'daytona_sandbox_not_found'; }

Try / catch

try { await sandboxOp(); } catch (e) { if (isSandboxNotFound(e)) { return recreateSandboxFromSnapshot(); } throw e; // other errors remain retryable }

Prevention

When it happens

Trigger: Any Daytona SDK call inside the plugin (stop/exec, snapshot, or workspace ops around plugin.ts:2865) rejects with DaytonaNotFoundError because the sandbox was deleted (expired TTL, manual deletion in Daytona dashboard, account/region issue, or garbage collection).

Common situations: Sandbox auto-expired after idle timeout while a worker still held a cached reference; operator deleted sandboxes to free quota; Daytona cleaned up stale sandboxes; multi-worker setups where another worker already exported and removed the workspace.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/c8011ab0324a7440. Report an issue: GitHub.