paperclipai/paperclip · error · Error

E2B sandbox environments require an API key in config or E2B

Error message

E2B sandbox environments require an API key in config or E2B_API_KEY.

What it means

Thrown by resolveApiKey in the E2B provider when neither the driver config's apiKey field nor the E2B_API_KEY environment variable yields a non-empty string. resolveApiKey is called by createSandbox on every Sandbox.create, so the error surfaces on any lease/probe operation that needs to spin up an E2B sandbox.

Source

Thrown at packages/plugins/sandbox-providers/e2b/src/plugin.ts:52

  const template = typeof raw.template === "string" && raw.template.trim().length > 0
    ? raw.template.trim()
    : "base";
  const timeoutMs = Number(raw.timeoutMs ?? 3_600_000);
  return {
    template,
    apiKey: typeof raw.apiKey === "string" && raw.apiKey.trim().length > 0 ? raw.apiKey.trim() : null,
    timeoutMs: Number.isFinite(timeoutMs) ? Math.trunc(timeoutMs) : 3_600_000,
    reuseLease: raw.reuseLease === true,
  };
}

function resolveApiKey(config: E2bDriverConfig): string {
  if (config.apiKey) {
    return config.apiKey;
  }
  const envApiKey = process.env.E2B_API_KEY?.trim() ?? "";
  if (!envApiKey) {
    throw new Error("E2B sandbox environments require an API key in config or E2B_API_KEY.");
  }
  return envApiKey;
}

async function createSandbox(config: E2bDriverConfig): Promise<Sandbox> {
  const options = {
    apiKey: resolveApiKey(config),
    timeoutMs: config.timeoutMs,
    metadata: {
      paperclipProvider: "e2b",
    },
  };
  return await Sandbox.create(config.template, options);
}

function formatErrorMessage(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

View on GitHub (pinned to 67001ec6eb)

Solutions

Export E2B_API_KEY in the worker environment (export E2B_API_KEY=...) or add it to the loaded .env.
Pass apiKey explicitly in the E2B driver config blob stored for the environment.
Verify the value is non-empty after trim and that the process actually has the env var (print process.env.E2B_API_KEY?.length, never the value).

Example fix

# before
# (nothing set)

# after
export E2B_API_KEY=e2b_********************
# or in driver config:
# { "apiKey": "e2b_...", "template": "base" }

Defensive patterns

Strategy: validation

Validate before calling

function ensureE2bKey(config: { apiKey?: string | null }): string {
  const fromEnv = process.env.E2B_API_KEY?.trim() ?? '';
  const key = (config.apiKey && config.apiKey.trim()) || fromEnv;
  if (!key) throw new Error('E2B_API_KEY (or config.apiKey) must be set');
  return key;
}

Type guard

function hasE2bKey(config: { apiKey?: string | null }): boolean {
  return Boolean((config.apiKey && config.apiKey.trim()) || (process.env.E2B_API_KEY && process.env.E2B_API_KEY.trim()));
}

Try / catch

try {
  await plugin.onEnvironmentProbe(params);
} catch (err) {
  if (err instanceof Error && /E2B_API_KEY/.test(err.message)) {
    return { ok: false, error: 'E2B API key not configured' };
  }
  throw err;
}

Prevention

Add a boot-time config check that fails the worker fast when E2B is configured but the key is missing.
Keep the key in a secret manager and inject via env; never log the value.

When it happens

Trigger: Any E2B provider call (probe, acquireLease, realizeWorkspace) invoked with config.apiKey unset/blank AND process.env.E2B_API_KEY unset/blank/whitespace-only. parseDriverConfig trims and nulls blank apiKeys, so a whitespace-only config value also falls through to the env lookup.

Common situations: Fresh dev/CI environment where E2B_API_KEY was never exported; .env file not loaded by the worker process; key redacted to empty by a secret manager; config propagated from a template that omitted apiKey.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/222526aa49e42d58. Report an issue: GitHub.