mastra-ai/mastra · error

INVALID_KEY

INVALID_KEY

Error message

INVALID_KEY | LICENSE_EXPIRED | LICENSE_REVOKED | RATE_LIMITED

What it means

This is the license validation error-code union returned by the Mastra license server in a LicenseValidationError body: INVALID_KEY (unknown/malformed key), LICENSE_EXPIRED, LICENSE_REVOKED, or RATE_LIMITED. When validation returns valid:false with one of these codes, the client marks the license invalid, logs 'License validation failed: <code> - <reason>', clears cached state, and enterprise features become unavailable.

Source

Thrown at packages/core/src/license/index.ts:15

import type { IMastraLogger } from '../logger';

export interface LicenseValidationSuccess {
  valid: true;
  /** Feature entitlements granted by the license (e.g. 'rbac', 'sso', 'fga') */
  entitlements: string[];
  /** Plan tier the license was issued for (e.g. 'teams', 'enterprise') */
  planTier: string;
  expiresAt: string | null;
  leaseTtlSeconds: number;
}

export interface LicenseValidationError {
  valid: false;
  code: 'INVALID_KEY' | 'LICENSE_EXPIRED' | 'LICENSE_REVOKED' | 'RATE_LIMITED';
  reason: string;
}

export type LicenseValidationResponse = LicenseValidationSuccess | LicenseValidationError;

export type LicenseMode = 'enterprise' | 'open-source';

export type LicenseStatus = 'pending' | 'valid' | 'invalid';

export interface LicenseSnapshot {
  mode: LicenseMode;
  status: LicenseStatus;
  entitlements: string[] | null;
  planTier: string | null;
  expiresAt: string | null;
}

export class LicenseClient {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check the logged reason string and the specific code in the validation response
2. For INVALID_KEY: verify MASTRA_LICENSE_KEY env var — no typos, whitespace, or stale keys — and re-copy from the dashboard
3. For LICENSE_EXPIRED/LICENSE_REVOKED: renew or reissue the key in the Mastra dashboard, then update the env var and restart
4. For RATE_LIMITED: back off and retry; reduce validation frequency or number of clients sharing the key
5. If you intend to run open-source only, remove the license key so the process runs in open-source mode

Example fix

// before
MASTRA_LICENSE_KEY="  sk-live-abc12 "  // stale/wrong key
// after
MASTRA_LICENSE_KEY="sk-live-valid-key-from-dashboard"  # exact, current key

const key = process.env.MASTRA_LICENSE_KEY?.trim();
if (!key || key.length < 8) {
  throw new Error('MASTRA_LICENSE_KEY is missing or malformed');
}

const result = await validateLicense(key); // LicenseValidationResponse
if (!result.valid) {
  switch (result.code) {
    case 'INVALID_KEY':      /* re-copy key from dashboard */ break;
    case 'LICENSE_EXPIRED':  /* renew */ break;
    case 'LICENSE_REVOKED':  /* reissue */ break;
    case 'RATE_LIMITED':     /* back off and retry */ break;
  }
}

When it happens

Trigger: Validation response body has valid:false with code INVALID_KEY (typo/mistyped key, key deleted in dashboard, wrong env var), LICENSE_EXPIRED (past expiresAt), LICENSE_REVOKED (manually revoked), or RATE_LIMITED (too many validation requests — though RATE_LIMITED is treated as transient and thrown instead).

Common situations: Copy-pasting a license key with whitespace or quotes into an env var; trial license expired; key rotated/revoked after a plan change; CI sharing one key across many runners hitting RATE_LIMITED.

Related errors

• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO
• heartbeatMs must be a finite number no greater than ${MAX_TI
• Expected a PEM-encoded public key or certificate string for
• terminationGraceMs must be greater than zero.

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