{"record":{"id":"6b5809a56fba4002","repo":"mastra-ai/mastra","slug":"session-settings-are-unavailable","errorCode":null,"errorMessage":"Session settings are unavailable","messagePattern":"Session settings are unavailable","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/factory-ui/src/hooks/useAgentControllerSettings.ts","lineNumber":36,"sourceCode":"  agentControllerId,\n  resourceId,\n  scope,\n  baseUrl = '',\n  enabled = true,\n}: UseAgentControllerSettingsArgs) {\n  const { session } = createAgentControllerClient({\n    agentControllerId,\n    resourceId,\n    scope,\n    baseUrl,\n    enabled,\n  });\n\n  return useQuery({\n    queryKey: queryKeys.agentControllerSettings(agentControllerId, resourceId, scope),\n    queryFn: async () => {\n      const state = await requireAgentControllerSession(session).state();\n      if (!state.settings) throw new Error('Session settings are unavailable');\n      return state.settings;\n    },\n    enabled: enabled && Boolean(session),\n  });\n}\n","sourceCodeStart":18,"sourceCodeEnd":42,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory-ui/src/hooks/useAgentControllerSettings.ts#L18-L42","documentation":"The `useAgentControllerSettings` hook loads the agent controller session state and returns `state.settings`. If the session state exists but has no `settings` payload, the query throws this error instead of returning undefined, signaling the settings are not (yet) available for this session.","triggerScenarios":"`requireAgentControllerSession(session).state()` resolves to a state object with `settings` undefined/null — e.g., queried before the controller finished initializing, or the agent controller does not expose settings for this resource/scope.","commonSituations":"Query enabled before the session handshake completed; agent controller version lacks the settings feature; wrong resourceId/scope producing a state without settings; transient backend state where settings were not persisted yet.","solutions":["Gate the query until the controller session is fully initialized (enabled flag / wait for session ready)","Retry — settings usually appear once the controller finishes loading (React Query retry)","Verify the agent controller version supports settings for this resource and scope","If settings are legitimately optional, treat this state as empty rather than an error"],"exampleFix":"// before\nif (!state.settings) throw new Error('Session settings are unavailable');\n// after (caller-side tolerance)\nconst { data: settings, isError } = useAgentControllerSettings(...);\nconst effective = isError ? DEFAULT_SETTINGS : settings;","handlingStrategy":"fallback","validationCode":"// before querying, confirm the controller session is ready\nconst sessionState = await requireAgentControllerSession(session).state();\nconst hasSettings = sessionState?.settings != null;\n// pass enabled: enabled && Boolean(session) && hasSettingsReady","typeGuard":"function hasSettings(state: AgentControllerState | undefined): state is AgentControllerState & { settings: SessionSettings } {\n  return !!state && state.settings != null;\n}","tryCatchPattern":"const { data: settings, isError } = useAgentControllerSettings(agentControllerId, resourceId, scope);\nconst effectiveSettings = isError || !settings ? DEFAULT_SETTINGS : settings;","preventionTips":["Gate the query on session readiness, not just session existence","Retry transiently (React Query retry) since settings often appear after initialization","Verify controller version supports settings for the given scope","Treat missing settings as empty config when they are optional"],"tags":["react-query","settings","session","factory-ui"],"backgroundTag":"session-state-unavailable","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}