{"record":{"id":"142f33b4fa120801","repo":"mastra-ai/mastra","slug":"the-server-did-not-persist-the-requested-settings","errorCode":null,"errorMessage":"The server did not persist the requested settings","messagePattern":"The server did not persist the requested settings","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/factory-ui/src/hooks/useUpdateAgentControllerSettingsMutation.ts","lineNumber":76,"sourceCode":"\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        );\n      }\n\n      return { previousSettings };\n    },\n    onError: async (error, _updates, context) => {","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory-ui/src/hooks/useUpdateAgentControllerSettingsMutation.ts#L58-L94","documentation":"After setState succeeds and the state read-back returns, the mutation compares the persisted settings against the requested updates using settingsIncludeUpdates. If the server's persisted state is missing settings or does not contain the requested values, it throws 'The server did not persist the requested settings', signaling an optimistic-update rollback is needed and the server rejected/ignored the change.","triggerScenarios":"The agent controller accepted setState but the subsequent state() returned settings that omit or diverge from the requested keys — server-side validation silently dropped a field, a concurrent writer overwrote the settings, or a schema change renamed a settings key.","commonSituations":"Two clients editing settings simultaneously; server version older/newer than client so a settings key isn't recognized; transient server bug persisting partial state; client sending a key the server no longer supports.","solutions":["Inspect updates for unsupported/renamed settings keys and align the client with the server's settings schema.","Implement the mutation's onError/onSettled rollback (it caches the pre-mutate snapshot via onMutate) and surface a 'settings conflict' message to the user.","Retry the update once after refetching settings to rule out a concurrent-writer race."],"exampleFix":"// before\nmutate({ temperature: 0.9 }); // silently dropped by server\n\n// after\nmutate({ temperature: 0.9 }, {\n  onError: () => {\n    queryClient.invalidateQueries({ queryKey: settingsQueryKey });\n    notify('Settings update was not persisted; please retry');\n  },\n});","handlingStrategy":"try-catch","validationCode":"// send only known settings keys\nconst safeUpdates = pickKnownKeys(updates, SERVER_SETTINGS_KEYS);","typeGuard":"function settingsIncludeUpdates(s: AgentControllerSessionSettings, u: SettingsUpdates): boolean { /* provided by lib */ return Object.entries(u).every(([k, v]) => (s as any)[k] === v); }","tryCatchPattern":"mutate(updates, {\n  onError: err => {\n    if ((err as Error).message === 'The server did not persist the requested settings') {\n      queryClient.invalidateQueries({ queryKey: settingsQueryKey });\n      notify('Server did not apply your changes');\n    }\n  },\n});","preventionTips":["Keep client settings keys aligned with the server schema (add contract tests).","Handle concurrent editors by refetching settings after conflicts.","Always implement the onMutate snapshot rollback in onError."],"tags":["consistency","agent-controller","verification","react-query"],"backgroundTag":"server-state-mismatch","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}