mastra-ai/mastra · error

Session settings are unavailable

Error message

Session settings are unavailable

What it means

The `useAgentControllerSettings` hook loads the agent controller session state and returns `state.settings`. If the session state exists but has no `settings` payload, the query throws this error instead of returning undefined, signaling the settings are not (yet) available for this session.

Source

Thrown at mastracode/factory-ui/src/hooks/useAgentControllerSettings.ts:36

  agentControllerId,
  resourceId,
  scope,
  baseUrl = '',
  enabled = true,
}: UseAgentControllerSettingsArgs) {
  const { session } = createAgentControllerClient({
    agentControllerId,
    resourceId,
    scope,
    baseUrl,
    enabled,
  });

  return useQuery({
    queryKey: queryKeys.agentControllerSettings(agentControllerId, resourceId, scope),
    queryFn: async () => {
      const state = await requireAgentControllerSession(session).state();
      if (!state.settings) throw new Error('Session settings are unavailable');
      return state.settings;
    },
    enabled: enabled && Boolean(session),
  });
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Gate the query until the controller session is fully initialized (enabled flag / wait for session ready)
2. Retry — settings usually appear once the controller finishes loading (React Query retry)
3. Verify the agent controller version supports settings for this resource and scope
4. If settings are legitimately optional, treat this state as empty rather than an error

Example fix

// before
if (!state.settings) throw new Error('Session settings are unavailable');
// after (caller-side tolerance)
const { data: settings, isError } = useAgentControllerSettings(...);
const effective = isError ? DEFAULT_SETTINGS : settings;

// before querying, confirm the controller session is ready
const sessionState = await requireAgentControllerSession(session).state();
const hasSettings = sessionState?.settings != null;
// pass enabled: enabled && Boolean(session) && hasSettingsReady

function hasSettings(state: AgentControllerState | undefined): state is AgentControllerState & { settings: SessionSettings } {
  return !!state && state.settings != null;
}

const { data: settings, isError } = useAgentControllerSettings(agentControllerId, resourceId, scope);
const effectiveSettings = isError || !settings ? DEFAULT_SETTINGS : settings;

When it happens

Trigger: `requireAgentControllerSession(session).state()` resolves to a state object with `settings` undefined/null — e.g., queried before the controller finished initializing, or the agent controller does not expose settings for this resource/scope.

Common situations: Query enabled before the session handshake completed; agent controller version lacks the settings feature; wrong resourceId/scope producing a state without settings; transient backend state where settings were not persisted yet.

Related errors

• Failed to load models (${res.status})
• Failed to load Factories
• Factory project is required
• Factory project is required
• Factory project is required

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