mastra-ai/mastra · error

Unsupported browser provider: ${provider}

Error message

Unsupported browser provider: ${provider}

What it means

The browser onboarding settings factory only supports the providers 'stagehand' and 'agent-browser'. If settings.provider is any other string, the factory throws `Unsupported browser provider: ${provider}`. This is a configuration validation error at the end of the provider-selection switch.

Source

Thrown at mastracode/sdk/src/onboarding/settings.ts:1362

        middleware: createCodexMiddleware(),
      } as any;
    }

    return cdpUrl
      ? new StagehandBrowser({ ...launchConfig, cdpUrl, scope: 'shared', ...stagehandOpts })
      : new StagehandBrowser({ ...launchConfig, ...stagehandOpts });
  } else if (provider === 'agent-browser') {
    const { AgentBrowser } = await import('@mastra/agent-browser');
    const agentBrowserOpts = {
      storageState: agentBrowser?.storageState,
      recording: browserRecordingOptions(),
    };
    return cdpUrl
      ? new AgentBrowser({ ...launchConfig, cdpUrl, scope: 'shared', ...agentBrowserOpts })
      : new AgentBrowser({ ...launchConfig, ...agentBrowserOpts, scope });
  }

  throw new Error(`Unsupported browser provider: ${provider}`);
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set settings.provider to 'stagehand' or 'agent-browser'.
2. Check for typos/renames (e.g. 'agent-browser' not 'agentbrowser' or 'agent_browser') in the stored settings.
3. If migrating from an older version, migrate the stored provider value to a supported name before invoking the factory.
4. Validate provider with an allowlist check before calling the factory and surface a friendly settings error.

Example fix

// before
const settings = { provider: 'playwright', headless: true, ... };
const browser = await createBrowser(settings); // throws
// after
const settings = { provider: 'agent-browser', headless: true, ... };
const browser = await createBrowser(settings);

const SUPPORTED_PROVIDERS = ['stagehand', 'agent-browser'] as const;
type Provider = typeof SUPPORTED_PROVIDERS[number];
function assertValidProvider(p: string): asserts p is Provider {
  if (!SUPPORTED_PROVIDERS.includes(p as Provider)) {
    throw new Error(`provider must be one of ${SUPPORTED_PROVIDERS.join(', ')}, got '${p}'`);
  }
}
assertValidProvider(settings.provider);

function isSupportedProvider(p: string): p is 'stagehand' | 'agent-browser' {
  return p === 'stagehand' || p === 'agent-browser';
}

try {
  return await createBrowser(settings);
} catch (e) {
  if (e.message.startsWith('Unsupported browser provider:')) {
    const fallback = { ...settings, provider: 'agent-browser' as const };
    return createBrowser(fallback); // or re-prompt the user for settings
  }
  throw e;
}

When it happens

Trigger: Calling the browser factory with settings.provider set to anything other than 'stagehand' or 'agent-browser' — e.g. 'playwright', 'chrome', 'puppeteer', an empty string, or a misspelled/renamed provider in the settings file.

Common situations: Editing the onboarding/settings store by hand with an old or invented provider name; a config migration or version change renaming providers; copying settings from another tool that uses different provider identifiers.

Related errors

• browser_close requires agent.threadId when browser scope is
• Invalid browser configuration: "cdpUrl" and "scope: 'thread'
• Invalid browser configuration: "cdpUrl" cannot be used with
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}

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