{"record":{"id":"9c17e760821ddad0","repo":"mastra-ai/mastra","slug":"error-9c17e7","errorCode":null,"errorMessage":"error","messagePattern":"error","errorType":"exception","errorClass":"SettingsUpdateVerificationError","httpStatus":null,"severity":"error","filePath":"mastracode/factory-ui/src/hooks/useUpdateAgentControllerSettingsMutation.ts","lineNumber":71,"sourceCode":"  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    },\n    onMutate: async updates => {\n      await queryClient.cancelQueries({ queryKey: settingsQueryKey, exact: true });\n      const previousSettings = queryClient.getQueryData<AgentControllerSessionSettings>(settingsQueryKey);\n\n      if (previousSettings) {\n        queryClient.setQueryData<AgentControllerSessionSettings>(\n          settingsQueryKey,\n          applySettingsUpdates(previousSettings, updates),\n        );","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory-ui/src/hooks/useUpdateAgentControllerSettingsMutation.ts#L53-L89","documentation":"After applying updates via activeSession.setState, the mutation re-reads state with activeSession.state() to verify persistence. If that read fails, the raw error is wrapped in SettingsUpdateVerificationError (whose message is 'error'). This distinguishes a read-back failure from an apply failure, letting callers know the server round-trip for verification did not complete.","triggerScenarios":"activeSession.state() throwing — the agent controller WebSocket/connection dropped right after setState, the session was closed by the server, or a network interruption occurred during the read-back.","commonSituations":"Flaky network or laptop sleep mid-update; server restarted the agent controller session; WebSocket auth token expired between connect and state read.","solutions":["Catch SettingsUpdateVerificationError in the mutation's onError and retry the update after reconnecting the agent controller session.","Check the underlying cause (error property on the wrapper) for connection vs auth issues and re-create the session if closed.","Add connection state monitoring so updates are only attempted while the session is live."],"exampleFix":"// before\nmutate(updates); // errors surface generically\n\n// after\nmutate(updates, {\n  onError: err => {\n    if (err instanceof SettingsUpdateVerificationError) reconnectAndRetry();\n  },\n});","handlingStrategy":"retry","validationCode":"if (!activeSession || activeSession.closed) await reconnect(); // verify session liveness before setState","typeGuard":"const isVerificationError = (e: unknown): e is SettingsUpdateVerificationError => e instanceof SettingsUpdateVerificationError;","tryCatchPattern":"mutate(updates, { onError: async err => { if (isVerificationError(err)) { await reconnect(); mutate(updates); } } });","preventionTips":["Monitor WebSocket connection state and disable updates while disconnected.","Re-authenticate/reconnect sessions that have been idle beyond server TTL.","Distinguish verification errors from apply errors in telemetry."],"tags":["websocket","network","agent-controller","verification"],"backgroundTag":"state-verification-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}