What causes "The server did not persist the requested settings" in mastra-ai/mastra?

Inspect updates for unsupported/renamed settings keys and align the client with the server's settings schema.

The server did not persist the requested settings

Error message

The server did not persist the requested settings

What it means

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.

Source

Thrown at mastracode/factory-ui/src/hooks/useUpdateAgentControllerSettingsMutation.ts:76

  return useMutation({
    mutationFn: async (updates: SettingsUpdates) => {
      const current = queryClient.getQueryData<AgentControllerSessionSettings>(settingsQueryKey);
      if (!current) throw new Error('Session settings are unavailable');

      const activeSession = requireAgentControllerSession(session);
      await activeSession.setState({ ...updates });

      let persistedState;
      try {
        persistedState = await activeSession.state();
      } catch (error) {
        throw new SettingsUpdateVerificationError(error);
      }

      const persistedSettings = persistedState.settings;
      if (!persistedSettings || !settingsIncludeUpdates(persistedSettings, updates)) {
        throw new Error('The server did not persist the requested settings');
      }

      return persistedSettings;
    },
    onMutate: async updates => {
      await queryClient.cancelQueries({ queryKey: settingsQueryKey, exact: true });
      const previousSettings = queryClient.getQueryData<AgentControllerSessionSettings>(settingsQueryKey);

      if (previousSettings) {
        queryClient.setQueryData<AgentControllerSessionSettings>(
          settingsQueryKey,
          applySettingsUpdates(previousSettings, updates),
        );
      }

      return { previousSettings };
    },
    onError: async (error, _updates, context) => {

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
mutate({ temperature: 0.9 }); // silently dropped by server

// after
mutate({ temperature: 0.9 }, {
  onError: () => {
    queryClient.invalidateQueries({ queryKey: settingsQueryKey });
    notify('Settings update was not persisted; please retry');
  },
});

Defensive patterns

Strategy: try-catch

Validate before calling

// send only known settings keys
const safeUpdates = pickKnownKeys(updates, SERVER_SETTINGS_KEYS);

Type guard

function settingsIncludeUpdates(s: AgentControllerSessionSettings, u: SettingsUpdates): boolean { /* provided by lib */ return Object.entries(u).every(([k, v]) => (s as any)[k] === v); }

Try / catch

mutate(updates, {
  onError: err => {
    if ((err as Error).message === 'The server did not persist the requested settings') {
      queryClient.invalidateQueries({ queryKey: settingsQueryKey });
      notify('Server did not apply your changes');
    }
  },
});

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/142f33b4fa120801. Report an issue: GitHub.