mastra-ai/mastra · error

Session settings are unavailable

Error message

Session settings are unavailable

What it means

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.

Source

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

  if (updates.smartEditing !== undefined && settings.smartEditing !== updates.smartEditing) return false;
  return true;
}

export function useUpdateAgentControllerSettingsMutation({
  agentControllerId,
  resourceId,
  scope,
  baseUrl = '',
  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;
    },

View on GitHub (pinned to 75dd419e61)

Solutions

1. Wait for the settings query to succeed before rendering/enabling the settings form (check query.isSuccess).
2. Ensure the settings query uses the same key (agentControllerSettings(agentControllerId, resourceId, scope)) and is enabled with the same params used by the mutation.
3. If a submit can race loading, guard the call: only mutate when the cached settings are present.

Example fix

// before
const { mutate } = useUpdateAgentControllerSettingsMutation(...);
useEffect(() => { mutate(updates); }, [updates]);

// after
const settings = useQuery(queryKeys.agentControllerSettings(...));
useEffect(() => { if (settings.data) mutate(updates); }, [updates, settings.data]);

const settings = queryClient.getQueryData<AgentControllerSessionSettings>(settingsQueryKey);
if (!settings) return; // wait for settings query before allowing edits

const hasCachedSettings = (s: AgentControllerSessionSettings | undefined): s is AgentControllerSessionSettings => Boolean(s);

mutate(updates, { onError: err => { if ((err as Error).message === 'Session settings are unavailable') await refetchSettings(); } });

When it happens

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

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

Related errors

• Factory project is required
• Factory project is required
• Factory run requires a board work item
• Select a repository before starting a Factory run
• The server did not persist the requested settings

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