mastra-ai/mastra · critical · Error

[mastra/auth-ee] Agent Builder is configured but the EE modu

Error message

[mastra/auth-ee] Agent Builder is configured but the EE module (@mastra/core/auth/ee) could not be loaded.
Ensure @mastra/core is updated to a version that includes EE support.

What it means

Thrown when Agent Builder is configured/enabled but the dynamic import of @mastra/core/auth/ee fails, meaning the installed @mastra/core has no EE module. Since Agent Builder depends on the EE licensing layer, the adapter throws with guidance to update @mastra_core. Pre-existing [mastra/auth-ee] errors are rethrown as-is.

Source

Thrown at packages/server/src/server/server-adapter/index.ts:894

    const editor = this.mastra.getEditor();
    if (!editor?.hasEnabledBuilderConfig?.()) return;

    try {
      const { isEEEnabled } = await import('@mastra/core/auth/ee');
      if (!isEEEnabled()) {
        throw new Error(
          '[mastra/auth-ee] Agent Builder is configured but no valid EE license was found.\n' +
            'Agent Builder requires a Mastra Enterprise License for production use.\n' +
            'Set the MASTRA_EE_LICENSE environment variable with your license key.\n' +
            'Learn more: https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE',
        );
      }
    } catch (err) {
      if (err instanceof Error && err.message.startsWith('[mastra/auth-ee]')) {
        throw err;
      }
      // @mastra/core/auth/ee module not available — Agent Builder cannot function
      throw new Error(
        '[mastra/auth-ee] Agent Builder is configured but the EE module (@mastra/core/auth/ee) could not be loaded.\n' +
          'Ensure @mastra/core is updated to a version that includes EE support.',
      );
    }
  }

  /**
   * Validate route-level FGA policy coverage when an FGA provider opts into
   * startup checks.
   */
  async validateFGAPolicyCoverage(): Promise<void> {
    const serverConfig = this.mastra.getServer();
    const studioConfig = this.mastra.getStudio?.();
    // Check both server and studio FGA providers
    const fgaProvider = serverConfig?.fga ?? studioConfig?.fga;
    if (!fgaProvider) return;

    const customRoutes = (this.customApiRoutes ?? serverConfig?.apiRoutes ?? []).filter(

View on GitHub (pinned to 75dd419e61)

Solutions

Update @mastra/core to the latest version that includes EE support.
Clean and reinstall dependencies (pnpm install; optionally remove node_modules) and rebuild @mastra/core if in-workspace.
Verify the auth/ee export exists: check @mastra/core/package.json exports for './auth/ee'.
Align all @mastra/* package versions so peers resolve to a single @mastra/core copy.

Example fix

// before
pnpm --filter @mastra/server build // @mastra/core stale at pre-EE version

// after
pnpm install && pnpm --filter @mastra/core build && pnpm --filter @mastra/server build

Defensive patterns

Strategy: validation

Validate before calling

if (mastra.getEditor()?.hasEnabledBuilderConfig?.()) {
  try {
    await import('@mastra/core/auth/ee');
  } catch {
    throw new Error('Agent Builder enabled but @mastra/core/auth/ee is missing — update @mastra/core to a version with EE support');
  }
}

Type guard

function isEeModuleMissingForBuilder(err: unknown): boolean {
  return err instanceof Error &&
    err.message.includes('[mastra/auth-ee]') &&
    err.message.includes('Agent Builder') &&
    err.message.includes('could not be loaded');
}

Try / catch

try {
  await startServer(mastra);
} catch (e) {
  if (isEeModuleMissingForBuilder(e)) {
    console.error('Upgrade @mastra/core so the EE module needed by Agent Builder resolves.');
    process.exitCode = 1;
    return;
  }
  throw e;
}

Prevention

Pin all @mastra/* packages to matching versions in package.json.
Rebuild @mastra/core dist in monorepos before starting the server.
Smoke-test EE-dependent boots in CI with a build that includes the auth/ee export.
Reinstall dependencies after any upgrade touching @mastra/core.

When it happens

Trigger: Enabling Agent Builder with an @mastra/core version lacking the auth/ee subpath export, a corrupted or partially installed node_modules, or a build/bundler setup that breaks dynamic import of the subpath.

Common situations: Mixed package versions in a pnpm workspace (stale @mastra/core build); forgetting `pnpm install` after upgrading server packages; using a bundler that cannot resolve dynamic imports of package subpath exports; running from a stale dist directory.

Related errors

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