mastra-ai/mastra · critical · Error

[mastra/auth-ee] Agent Builder is configured but no valid EE

Error message

[mastra/auth-ee] Agent Builder is configured but no valid EE license was found.
Agent Builder requires a Mastra Enterprise License for production use.
Set the MASTRA_EE_LICENSE environment variable with your license key.
Learn more: https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE

What it means

Startup error thrown when the Mastra editor has an enabled Agent Builder configuration (editor.hasEnabledBuilderConfig()) but no valid EE license is present (isEEEnabled() is false). Agent Builder is an enterprise-gated feature, so the server refuses to start rather than exposing it unlicensed.

Source

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

      throw new Error(
        `[mastra/auth-ee] ${configuredFeatures.join(' and ')} ${configuredFeatures.length === 1 ? 'is' : 'are'} 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 that an Agent Builder configuration has a valid EE license.
   * Throws if the editor is configured with builder support but no valid EE license is available.
   */
  async validateAgentBuilderLicense(): Promise<void> {
    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.',
      );
    }
  }

View on GitHub (pinned to 75dd419e61)

Solutions

Set MASTRA_EE_LICENSE with a valid license key in the server's environment.
If Agent Builder is not needed, disable the builder configuration in the editor/mastra config.
Confirm the env var name and value are correct and loaded before server boot.
Renew the license if it has expired.

Example fix

// before
new Mastra({ editor: { builder: { enabled: true } } }); // no license in env

// after
// export MASTRA_EE_LICENSE=<key> in the deployment environment
new Mastra({ editor: { builder: { enabled: true } } });

Defensive patterns

Strategy: validation

Validate before calling

if (mastra.getEditor()?.hasEnabledBuilderConfig?.() && !process.env.MASTRA_EE_LICENSE) {
  throw new Error('Agent Builder is enabled but MASTRA_EE_LICENSE is not set; provide a license or disable the builder config');
}

Type guard

function builderRequiresLicense(editor: unknown): boolean {
  return typeof editor === 'object' && editor !== null &&
    typeof (editor as any).hasEnabledBuilderConfig === 'function' &&
    (editor as any).hasEnabledBuilderConfig() === true;
}

Try / catch

try {
  await startServer(mastra);
} catch (e) {
  if (e instanceof Error && e.message.includes('Agent Builder') && e.message.includes('no valid EE license')) {
    console.error('Disable Agent Builder or set MASTRA_EE_LICENSE with a valid enterprise key.');
    process.exitCode = 1;
    return;
  }
  throw e;
}

Prevention

Gate Agent Builder enablement behind the presence of MASTRA_EE_LICENSE in config code.
Keep license env vars in all environments where builder config is enabled, including dev.
Alert on license expiry so Agent Builder doesn't fail boot unexpectedly.

When it happens

Trigger: Enabling Agent Builder in the editor/mastra config while MASTRA_EE_LICENSE is unset, invalid, or not visible to the server process, and then booting the server via server-adapter.

Common situations: Turning on Agent Builder locally without a license to try it; license configured in local .env but not in the deployed environment; expired enterprise license; environment variable name typo (e.g. MAESTRA_EE_LICENSE).

Related errors

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