{"record":{"id":"412bc78c171e9082","repo":"mastra-ai/mastra","slug":"handleautoversioning-returned-undefined","errorCode":null,"errorMessage":"handleAutoVersioning returned undefined","messagePattern":"handleAutoVersioning returned undefined","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/server/src/server/handlers/stored-agents.ts","lineNumber":941,"sourceCode":"\n      // Filter out undefined values to get only the config fields that were provided\n      const providedConfigFields = Object.fromEntries(Object.entries(configFields).filter(([_, v]) => v !== undefined));\n\n      // Handle auto-versioning with retry logic for race conditions\n      // This creates a new version if there are meaningful config changes.\n      const autoVersionResult = await handleAutoVersioning(\n        agentsStore as unknown as VersionedStoreInterface,\n        storedAgentId,\n        'agentId',\n        AGENT_SNAPSHOT_CONFIG_FIELDS,\n        existing,\n        updatedAgent,\n        providedConfigFields,\n        changeMessage ? { changeMessage } : undefined,\n      );\n\n      if (!autoVersionResult) {\n        throw new Error('handleAutoVersioning returned undefined');\n      }\n\n      // In code mode, local saves should overwrite the most recent saved\n      // snapshot rather than creating new draft versions on every keystroke\n      // batch. Version history is intended to track commits, not raw saves.\n      // We collapse the freshly created version onto the previous one by\n      // deleting the prior latest version, leaving a single rolling snapshot.\n      // When the user explicitly provides a changeMessage we treat that as a\n      // commit and keep the new version as a discrete history entry.\n      const isCodeSource = mastra.getEditor?.()?.getSource?.() === 'code';\n      if (isCodeSource && autoVersionResult.versionCreated && !changeMessage) {\n        const { versions } = await agentsStore.listVersions({ agentId: storedAgentId, perPage: 2 });\n        const previousVersion = versions[1];\n        const isPublishedVersion = previousVersion?.id === existing.activeVersionId;\n        if (previousVersion && !isPublishedVersion) {\n          await agentsStore.deleteVersion(previousVersion.id);\n        }\n      }","sourceCodeStart":923,"sourceCodeEnd":959,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/stored-agents.ts#L923-L959","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run storage migrations / upgrade the storage adapter so agent versioning tables and APIs exist","Upgrade @mastra/core/server packages to a version where handleAutoVersioning always returns a result for valid inputs","Check for concurrent saves to the same agent that may race the versioning logic; serialize updates on the client","If using a custom editor implementation, ensure agent.autoVersioning returns the created version record rather than void/undefined"],"exampleFix":"// before\nawait editor.agent.update(id, input); // no version bookkeeping\n\n// after\nconst version = await editor.agent.autoVersioning?.(input);\nif (!version) throw new Error('agent versioning returned no result');","handlingStrategy":"try-catch","validationCode":"const version = await editor.agent.update(id, input);\nif (version == null) console.warn('auto-versioning returned no result; storage may not support agent versions');","typeGuard":"function isVersionResult(v: unknown): v is { versionId: string } {\n  return !!v && typeof v === 'object' && 'versionId' in v;\n}","tryCatchPattern":"try {\n  await updateStoredAgent(id, patch);\n} catch (e) {\n  if (/handleAutoVersioning returned undefined/.test(String(e?.message))) {\n    // run storage migrations / verify versioning support, then retry once\n  } else throw e;\n}","preventionTips":["Run storage migrations on deploy so version tables exist","Serialize concurrent edits to the same agent","Test the update flow against the real storage adapter, not only mocks"],"tags":["versioning","internal-error","http-500","storage"],"backgroundTag":"versioning-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}