CreateOS requires an API key in the environment config or…

Error message

CreateOS requires an API key in the environment config or CREATEOS_API_KEY.

What it means

resolveApiKey resolves the API key from the environment config or the CREATEOS_API_KEY environment variable and rejects empty keys and keys containing CR, LF, or NUL. A missing key means the plugin cannot authenticate any CreateOS request, so it fails fast before making network calls.

Solutions

Set CREATEOS_API_KEY in the process environment (export CREATEOS_API_KEY=... or add to the CI/secret store) and restart the process.
Or set apiKey explicitly in the CreateOS environment config.
Trim the key value and remove embedded newlines/whitespace from however it is stored.
Verify the variable name is exactly CREATEOS_API_KEY (no typos, no workspace-local .env being ignored).

Example fix

// before
const key = process.env.CREATEOS_API_KEY; // undefined in CI
// after
export CREATEOS_API_KEY="ck_live_..." && pnpm dev

Defensive patterns

Strategy: try-catch

Validate before calling

const key = cfg.apiKey ?? process.env.CREATEOS_API_KEY?.trim();
if (!key || /[\r\n\0]/.test(key)) throw new Error('CREATEOS_API_KEY must be set, trimmed, and free of line breaks');

Try / catch

try {
  const plugin = new CreateosPlugin(cfg);
} catch (e) {
  if (e.message.includes('CreateOS requires an API key')) {
    throw new Error('Set CREATEOS_API_KEY in the environment or apiKey in the config: ' + e.message);
  }
  throw e;
}

Prevention

Assert the secret is present at process startup before spawning work
Trim keys when reading from files or secret stores
Use exact variable name CREATEOS_API_KEY and verify it in CI logs (never print the value)

When it happens

Trigger: Calling resolveApiKey (via the plugin constructor or account method) when both config.apiKey and process.env.CREATEOS_API_KEY are unset/empty/whitespace, or the resolved key contains a newline, carriage return, or NUL character.

Common situations: CREATEOS_API_KEY not exported in the shell/CI job or container; key pasted from a file with a trailing newline; key set to empty string in a .env file; running in an environment where the env var was not mounted.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/a444291c7b46b18c. Report an issue: GitHub.

Appendix: source

Thrown at packages/plugins/sandbox-providers/createos/src/config.ts:58

  }
  return {
    apiUrl: url.origin,
    apiKey: text("apiKey"),
    shape,
    rootfs: text("rootfs"),
    region: text("region"),
    timeoutMs,
    reuseLease: raw.reuseLease === true,
  };
}

export function resolveApiKey(config: CreateosConfig): string {
  if (!config.apiKey && config.apiUrl !== "https://api.sb.createos.sh") {
    throw new Error("Custom CreateOS API endpoints require an explicit environment API key; the host fallback is only available for https://api.sb.createos.sh.");
  }
  const key = config.apiKey ?? process.env.CREATEOS_API_KEY?.trim();
  if (!key || /[\r\n\0]/.test(key)) {
    throw new Error("CreateOS requires an API key in the environment config or CREATEOS_API_KEY.");
  }
  return key;
}

View on GitHub (pinned to 3f1d897a7c)