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

createSupermemoryContext (VoltAgent middleware) resolves the API key from options.apiKey or process.env.SUPERMEMORY_API_KEY and throws immediately when absent, preventing middleware construction without credentials.

Source

Thrown at packages/tools/src/voltagent/middleware.ts:73

		relatedMemories?: boolean
		summaries?: boolean
	}
	// Storage parameters
	metadata?: Record<string, string | number | boolean>
	searchMode?: "memories" | "documents" | "hybrid"
	entityContext?: string
}

/**
 * Creates a Supermemory middleware context.
 */
export const createSupermemoryContext = (
	containerTag: string,
	options: SupermemoryVoltAgent,
): SupermemoryMiddlewareContext => {
	const apiKey = options.apiKey ?? process.env.SUPERMEMORY_API_KEY
	if (!apiKey) {
		throw new Error(
			"SUPERMEMORY_API_KEY is not set — provide it via `options.apiKey` or set `process.env.SUPERMEMORY_API_KEY`",
		)
	}

	const {
		customId,
		mode = "profile",
		addMemory = "always", // VoltAgent default: save conversations by default for chat apps
		baseUrl,
		promptTemplate,
		threshold,
		limit,
		rerank,
		rewriteQuery,
		filters,
		include,
		metadata,
		searchMode,

View on GitHub (pinned to d436792e77)

Solutions

1. Set SUPERMEMORY_API_KEY in the agent's runtime environment
2. Pass apiKey explicitly in the SupermemoryVoltAgent options
3. For containers, ensure the var is declared in compose/k8s/compose env mapping

Example fix

// before
createSupermemoryContext('user-1', { customId: 'c1' })

// after
createSupermemoryContext('user-1', {
  customId: 'c1',
  apiKey: process.env.SUPERMEMORY_API_KEY!,
})

if (!process.env.SUPERMEMORY_API_KEY && !options.apiKey) throw new Error('configure SUPERMEMORY_API_KEY in the agent runtime')

When it happens

Trigger: Creating the Supermemory VoltAgent middleware without passing apiKey in an environment where SUPERMEMORY_API_KEY is not set.

Common situations: Env var present in dev shell but missing in the deployed agent runtime (Docker, serverless, orchestrator); .env file not copied into container; CI runs.

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
• customId is required and must be a non-empty string — provid
• Supermemory tools config accepts either projectId or contain
• customId is required — provide a non-empty string to group m

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