mastra-ai/mastra · error · Error

handleAutoVersioning returned undefined

Error message

handleAutoVersioning returned undefined

What it means

A defensive internal check (plain Error, caught and surfaced via handleError as 500) after calling the auto-versioning routine: `handleAutoVersioning(...)` returned undefined when the handler expected a version result. This indicates the versioning pipeline failed to produce a new/updated version record, usually due to a storage adapter or editor implementation issue.

Source

Thrown at packages/server/src/server/handlers/stored-agents.ts:941

      // Filter out undefined values to get only the config fields that were provided
      const providedConfigFields = Object.fromEntries(Object.entries(configFields).filter(([_, v]) => v !== undefined));

      // Handle auto-versioning with retry logic for race conditions
      // This creates a new version if there are meaningful config changes.
      const autoVersionResult = await handleAutoVersioning(
        agentsStore as unknown as VersionedStoreInterface,
        storedAgentId,
        'agentId',
        AGENT_SNAPSHOT_CONFIG_FIELDS,
        existing,
        updatedAgent,
        providedConfigFields,
        changeMessage ? { changeMessage } : undefined,
      );

      if (!autoVersionResult) {
        throw new Error('handleAutoVersioning returned undefined');
      }

      // In code mode, local saves should overwrite the most recent saved
      // snapshot rather than creating new draft versions on every keystroke
      // batch. Version history is intended to track commits, not raw saves.
      // We collapse the freshly created version onto the previous one by
      // deleting the prior latest version, leaving a single rolling snapshot.
      // When the user explicitly provides a changeMessage we treat that as a
      // commit and keep the new version as a discrete history entry.
      const isCodeSource = mastra.getEditor?.()?.getSource?.() === 'code';
      if (isCodeSource && autoVersionResult.versionCreated && !changeMessage) {
        const { versions } = await agentsStore.listVersions({ agentId: storedAgentId, perPage: 2 });
        const previousVersion = versions[1];
        const isPublishedVersion = previousVersion?.id === existing.activeVersionId;
        if (previousVersion && !isPublishedVersion) {
          await agentsStore.deleteVersion(previousVersion.id);
        }
      }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Run storage migrations / upgrade the storage adapter so agent versioning tables and APIs exist
2. Upgrade @mastra/core/server packages to a version where handleAutoVersioning always returns a result for valid inputs
3. Check for concurrent saves to the same agent that may race the versioning logic; serialize updates on the client
4. If using a custom editor implementation, ensure agent.autoVersioning returns the created version record rather than void/undefined

Example fix

// before
await editor.agent.update(id, input); // no version bookkeeping

// after
const version = await editor.agent.autoVersioning?.(input);
if (!version) throw new Error('agent versioning returned no result');

const version = await editor.agent.update(id, input);
if (version == null) console.warn('auto-versioning returned no result; storage may not support agent versions');

function isVersionResult(v: unknown): v is { versionId: string } {
  return !!v && typeof v === 'object' && 'versionId' in v;
}

try {
  await updateStoredAgent(id, patch);
} catch (e) {
  if (/handleAutoVersioning returned undefined/.test(String(e?.message))) {
    // run storage migrations / verify versioning support, then retry once
  } else throw e;
}

When it happens

Trigger: Stored-agent update where handleAutoVersioning silently returns undefined — e.g. a storage adapter that doesn't support agent versioning, an editor implementation that skips versioning under certain inputs, or a version write that no-ops without throwing.

Common situations: Storage adapters lacking versioning support (versions table missing/unmigrated); editor overrides in code-agent mode behaving differently from stored-agent mode; race conditions where a concurrent save collapsed/removed the version; bugs in custom editor implementations.

Related errors

• Failed to retrieve created version
• AcpAgent does not support resuming suspended generate calls
• AcpAgent does not support resuming suspended stream calls
• ACP prompt stopped before completing: ${response.stopReason}
• ClaudeSDKAgent resumeData must include a message.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/412bc78c171e9082. Report an issue: GitHub.