{"record":{"id":"3c9b4165b545b295","repo":"mastra-ai/mastra","slug":"session-settings-are-unavailable-3c9b41","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/useUpdateAgentControllerSettingsMutation.ts","lineNumber":62,"sourceCode":"  if (updates.smartEditing !== undefined && settings.smartEditing !== updates.smartEditing) return false;\n  return true;\n}\n\nexport function useUpdateAgentControllerSettingsMutation({\n  agentControllerId,\n  resourceId,\n  scope,\n  baseUrl = '',\n  enabled = true,\n}: AgentControllerMutationArgs) {\n  const queryClient = useQueryClient();\n  const { session } = createAgentControllerClient({ agentControllerId, resourceId, scope, baseUrl, enabled });\n  const settingsQueryKey = queryKeys.agentControllerSettings(agentControllerId, resourceId, scope);\n\n  return useMutation({\n    mutationFn: async (updates: SettingsUpdates) => {\n      const current = queryClient.getQueryData<AgentControllerSessionSettings>(settingsQueryKey);\n      if (!current) throw new Error('Session settings are unavailable');\n\n      const activeSession = requireAgentControllerSession(session);\n      await activeSession.setState({ ...updates });\n\n      let persistedState;\n      try {\n        persistedState = await activeSession.state();\n      } catch (error) {\n        throw new SettingsUpdateVerificationError(error);\n      }\n\n      const persistedSettings = persistedState.settings;\n      if (!persistedSettings || !settingsIncludeUpdates(persistedSettings, updates)) {\n        throw new Error('The server did not persist the requested settings');\n      }\n\n      return persistedSettings;\n    },","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory-ui/src/hooks/useUpdateAgentControllerSettingsMutation.ts#L44-L80","documentation":"useUpdateAgentControllerSettingsMutation reads the currently cached AgentControllerSessionSettings from the React Query cache (queryKeys.agentControllerSettings(...)) and throws 'Session settings are unavailable' if the cache entry is missing. The update is computed as a delta ({...updates}) applied on top of the current settings, so it cannot proceed without the cached baseline.","triggerScenarios":"Calling updateSettingsMutation.mutate(updates) before the settings query has populated the cache — e.g. the settings form submitted while the settings query was still loading, the query errored/was disabled, or the cache entry was evicted between render and submit.","commonSituations":"Auto-save effects firing on mount before data arrives; a form rendered from defaults while getQueryData returns undefined; invalidation removing the entry mid-edit; gcTime evicting the settings after tab inactivity.","solutions":["Wait for the settings query to succeed before rendering/enabling the settings form (check query.isSuccess).","Ensure the settings query uses the same key (agentControllerSettings(agentControllerId, resourceId, scope)) and is enabled with the same params used by the mutation.","If a submit can race loading, guard the call: only mutate when the cached settings are present."],"exampleFix":"// before\nconst { mutate } = useUpdateAgentControllerSettingsMutation(...);\nuseEffect(() => { mutate(updates); }, [updates]);\n\n// after\nconst settings = useQuery(queryKeys.agentControllerSettings(...));\nuseEffect(() => { if (settings.data) mutate(updates); }, [updates, settings.data]);","handlingStrategy":"validation","validationCode":"const settings = queryClient.getQueryData<AgentControllerSessionSettings>(settingsQueryKey);\nif (!settings) return; // wait for settings query before allowing edits","typeGuard":"const hasCachedSettings = (s: AgentControllerSessionSettings | undefined): s is AgentControllerSessionSettings => Boolean(s);","tryCatchPattern":"mutate(updates, { onError: err => { if ((err as Error).message === 'Session settings are unavailable') await refetchSettings(); } });","preventionTips":["Gate the settings form on the settings query's isSuccess.","Use the exact same query key for reads and the mutation.","Avoid auto-save effects before initial settings load completes."],"tags":["react-query","cache-miss","guard-clause","agent-controller"],"backgroundTag":"missing-cache-entry","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}