supermemoryai/supermemory · error · Error

withSupermemory: options must be an object with required con

Error message

withSupermemory: options must be an object with required containerTag and customId fields. The API changed in v2.0.0 — see https://docs.supermemory.ai/integrations/mastra for the new signature.

What it means

withSupermemory (Mastra wrapper) validates its options object at runtime and throws when it is missing, not an object, or lacking containerTag/customId. The v2.0.0 release changed the API from positional/looser arguments to a required options object.

Source

Thrown at packages/tools/src/mastra/wrapper.ts:80

 * )
 *
 * const agent = new Agent(config)
 * ```
 *
 * @throws {Error} When neither `options.apiKey` nor `process.env.SUPERMEMORY_API_KEY` are set
 */
export function withSupermemory<T extends AgentConfig>(
	config: T,
	options: SupermemoryMastraOptions,
): T {
	// Runtime guard for breaking API change - catch old 3-arg signature usage
	if (
		typeof options !== "object" ||
		options === null ||
		!options.containerTag ||
		!options.customId
	) {
		throw new Error(
			"withSupermemory: options must be an object with required containerTag and customId fields. " +
				"The API changed in v2.0.0 — see https://docs.supermemory.ai/integrations/mastra for the new signature.",
		)
	}

	validateApiKey(options.apiKey)

	const inputProcessor = new SupermemoryInputProcessor(options)
	const outputProcessor = new SupermemoryOutputProcessor(options)

	const existingInputProcessors = config.inputProcessors ?? []
	const existingOutputProcessors = config.outputProcessors ?? []

	// Supermemory input processor runs first (before other processors)
	const mergedInputProcessors: Processor[] = [
		inputProcessor,
		...existingInputProcessors,
	]

View on GitHub (pinned to d436792e77)

Solutions

1. Pass a single options object: withSupermemory({ containerTag, customId, apiKey })
2. Check the v2 migration docs at https://docs.supermemory.ai/integrations/mastra
3. Ensure containerTag and customId are non-empty strings
4. Set SUPERMEMORY_API_KEY env var so apiKey is optional

Example fix

// before (v1 style)
withSupermemory(mastra, 'my-container')

// after (v2)
withSupermemory({ containerTag: 'my-container', customId: 'session-123' })

if (!opts || typeof opts !== 'object' || !opts.containerTag || !opts.customId) throw new TypeError('withSupermemory requires { containerTag, customId }')

const isValidSupermemoryOptions = (o: unknown): o is { containerTag: string; customId: string } => !!o && typeof o === 'object' && typeof (o as any).containerTag === 'string' && typeof (o as any).customId === 'string' && (o as any).containerTag !== '' && (o as any).customId !== ''

When it happens

Trigger: Calling withSupermemory with no arguments, with the pre-2.0 positional signature, or with an options object missing containerTag or customId.

Common situations: Upgrading @supermemory/tools to v2.x without migrating call sites; passing only an apiKey; copy-pasting old examples from docs or blogs.

Related errors

• containerTag is required — provide a non-empty string to ide
• customId is required — provide a non-empty string to group m
• 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/a81aded60f99371c. Report an issue: GitHub.