supermemoryai/supermemory · critical · Error

SUPERMEMORY_API_KEY is not set — provide it via `options.api

Error message

SUPERMEMORY_API_KEY is not set — provide it via `options.apiKey` or set `process.env.SUPERMEMORY_API_KEY`

What it means

validateApiKey resolves the Supermemory API key from the explicit argument or process.env.SUPERMEMORY_API_KEY and throws when neither is present. All Supermemory tools/middleware call this before any network request.

Source

Thrown at packages/tools/src/shared/context.ts:55

		apiKey: options.apiKey,
		...(normalizedBaseUrl !== "https://api.supermemory.ai"
			? { baseURL: normalizedBaseUrl }
			: {}),
	})
}

/**
 * Validates that an API key is provided either via options or environment variable.
 *
 * @param apiKey - Optional API key from options
 * @returns The validated API key
 * @throws Error if no API key is available
 */
export function validateApiKey(apiKey?: string): string {
	const providedApiKey = apiKey ?? process.env.SUPERMEMORY_API_KEY

	if (!providedApiKey) {
		throw new Error(
			"SUPERMEMORY_API_KEY is not set — provide it via `options.apiKey` or set `process.env.SUPERMEMORY_API_KEY`",
		)
	}

	return providedApiKey
}

View on GitHub (pinned to d436792e77)

Solutions

1. Set SUPERMEMORY_API_KEY in your environment (.env.local for dev, platform secrets for deploy)
2. Or pass apiKey explicitly: withSupermemory(openai, { apiKey, ... })
3. Verify the env var actually reaches the runtime (console.log at boot in dev only)
4. For serverless, register the key as a platform secret, not just a local file

Example fix

// before
withSupermemory(openai, { containerTag, customId })

// after
withSupermemory(openai, { containerTag, customId, apiKey: process.env.SUPERMEMORY_API_KEY! })
// and in .env.local: SUPERMEMORY_API_KEY=sm_...

if (!process.env.SUPERMEMORY_API_KEY && !options?.apiKey) throw new Error('Missing Supermemory API key — configure SUPERMEMORY_API_KEY')

When it happens

Trigger: Using any Supermemory SDK entry point without options.apiKey while SUPERMEMORY_API_KEY is unset or empty in the environment (missing .env, not loaded in edge runtime, CI without secrets).

Common situations: Forgot to add the key to .env(.local); env var not propagated to Cloudflare Workers/Vercel edge (must be configured as a secret/vars); running tests in CI without the secret.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• SUPERMEMORY_API_KEY is not set — provide it via `options.api
• SUPERMEMORY_API_KEY is not set — provide it via `options.api
• Supermemory tools config accepts either projectId or contain
• customId is required — provide a non-empty string to group m
• customId is required and must be a non-empty string — provid

AI-assisted analysis of supermemoryai/supermemory@d436792e77 (2026-08-28). Data as JSON: /api/errors/b21088461c56ec90. Report an issue: GitHub.