mastra-ai/mastra · error · SettingsUpdateVerificationError

error

Error message

error

What it means

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.

Source

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

  enabled = true,
}: AgentControllerMutationArgs) {
  const queryClient = useQueryClient();
  const { session } = createAgentControllerClient({ agentControllerId, resourceId, scope, baseUrl, enabled });
  const settingsQueryKey = queryKeys.agentControllerSettings(agentControllerId, resourceId, scope);

  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),
        );

View on GitHub (pinned to 75dd419e61)

Solutions

1. Catch SettingsUpdateVerificationError in the mutation's onError and retry the update after reconnecting the agent controller session.
2. Check the underlying cause (error property on the wrapper) for connection vs auth issues and re-create the session if closed.
3. Add connection state monitoring so updates are only attempted while the session is live.

Example fix

// before
mutate(updates); // errors surface generically

// after
mutate(updates, {
  onError: err => {
    if (err instanceof SettingsUpdateVerificationError) reconnectAndRetry();
  },
});

if (!activeSession || activeSession.closed) await reconnect(); // verify session liveness before setState

const isVerificationError = (e: unknown): e is SettingsUpdateVerificationError => e instanceof SettingsUpdateVerificationError;

mutate(updates, { onError: async err => { if (isVerificationError(err)) { await reconnect(); mutate(updates); } } });

When it happens

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

Common situations: Flaky network or laptop sleep mid-update; server restarted the agent controller session; WebSocket auth token expired between connect and state read.

Related errors

• The server did not persist the requested settings
• No webSocketDebuggerUrl found in CDP version response from $
• Token exchange failed: ${error}
• Failed to fetch user info from Auth0
• Token exchange failed: ${error}

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