{"record":{"id":"ee54b456ef1b3e1a","repo":"mastra-ai/mastra","slug":"could-not-extract-settings-from-toolloopagent-the","errorCode":null,"errorMessage":"Could not extract settings from ToolLoopAgent. The agent may be from an incompatible version.","messagePattern":"Could not extract settings from ToolLoopAgent\\. The agent may be from an incompatible version\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/tool-loop-agent/utils.ts","lineNumber":33,"sourceCode":"\nexport function isToolLoopAgentLike(obj: any): obj is ToolLoopAgentLike {\n  if (!obj) return false;\n  if (obj instanceof ToolLoopAgent) return true;\n  return (\n    'version' in obj &&\n    typeof obj.version === 'string' &&\n    (obj.version === 'agent-v1' || obj.version.startsWith('agent-v'))\n  );\n}\n\n/**\n * Extracts the settings from a ToolLoopAgent instance.\n * ToolLoopAgent.settings is private in TypeScript but accessible at runtime.\n */\nexport function getSettings(agent: ToolLoopAgentLike): ToolLoopAgentSettings<any, any, any> {\n  const settings = (agent as unknown as { settings: ToolLoopAgentSettings<any, any, any> }).settings;\n  if (!settings) {\n    throw new Error('Could not extract settings from ToolLoopAgent. The agent may be from an incompatible version.');\n  }\n  return settings;\n}\n","sourceCodeStart":15,"sourceCodeEnd":37,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/tool-loop-agent/utils.ts#L15-L37","documentation":"getSettings reads the private settings field off a ToolLoopAgent instance at runtime (TypeScript privacy does not hide it at runtime). If the field is missing or falsy, the object passed in is not a ToolLoopAgent this code can work with — likely constructed by a different (incompatible) version of the library, a plain lookalike object, or an Agent of a different class — so the utility throws instead of failing later with confusing undefined-property errors.","triggerScenarios":"Calling getSettings(agent) (directly or via utilities that depend on it, like the settings accessor) with: an agent created by an older/newer @mastra/core that renames or removes .settings; a plain object that structurally resembles an agent; an Agent from a different package (e.g. @mastra/core/agent Agent) rather than ToolLoopAgent.","commonSituations":"Mixed @mastra/core versions in one install (duplicated dependencies from mismatched pnpm/npm resolution) so the instance was built by another copy of the library; passing a serialized/deserialized agent (JSON round-trip drops methods and private fields); passing a mock in tests.","solutions":["Ensure a single @mastra/core version is installed: run pnpm why @mastra/core / npm ls @mastra/core and dedupe mismatched copies.","Pass the actual ToolLoopAgent instance, not a serialized copy or a plain-object stand-in.","Upgrade all mastra packages to matching versions so the agent's internal shape matches what getSettings expects.","If you control the caller, construct the agent via the current ToolLoopAgent export rather than another Agent class."],"exampleFix":"// before\nimport { Agent } from '@mastra/core/agent';\ngetSettings(new Agent({ name: 'a', model, instructions })); // different class, no .settings\n\n// after\nimport { ToolLoopAgent } from '@mastra/core/tool-loop-agent';\ngetSettings(new ToolLoopAgent({ name: 'a', model, instructions }));","handlingStrategy":"type-guard","validationCode":"import { ToolLoopAgent } from '@mastra/core/tool-loop-agent';\nfunction assertToolLoopAgent(a: unknown): asserts a is ToolLoopAgent {\n  if (!(a instanceof ToolLoopAgent)) throw new TypeError('expected a ToolLoopAgent instance');\n  if (!('settings' in a) || !(a as any).settings) throw new TypeError('agent has no settings — version mismatch?');\n}","typeGuard":"function isToolLoopAgentLike(a: unknown): a is { settings: unknown } {\n  return !!a && typeof a === 'object' && 'settings' in a && (a as any).settings != null;\n}","tryCatchPattern":"try {\n  const settings = getSettings(agent);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Could not extract settings')) {\n    console.error('agent instance is incompatible — check @mastra/core versions and instance type');\n  } else throw err;\n}","preventionTips":["Pin a single @mastra/core version across all packages (npm ls / pnpm why to detect duplicates).","Never pass serialized (JSON round-tripped) agents to internal utilities.","Construct agents from the exact export your utility expects (ToolLoopAgent vs Agent).","Guard with a 'settings' in agent check before calling getSettings in generic code."],"tags":["agent","version-compatibility","reflection","internal-api"],"backgroundTag":"incompatible-agent-version","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}