mastra-ai/mastra · error · ModelNotAllowedError

Model not allowed by allowlist

Error message

Model not allowed by allowlist

What it means

assertModelAllowed validates a model candidate against the agent-builder EE provider allowlist via enforceModelAllowlist. If the candidate is not permitted (not found in the allowlist or matching a denied/offending entry), it throws ModelNotAllowedError, which the server adapter translates to HTTP 422 with a structured body. It enforces that write call sites only accept explicitly allowlisted models.

Source

Thrown at packages/core/src/agent-builder/ee/allowlist.ts:106

      return {
        ok: false,
        attempted: candidate,
        offendingLabel: candidate.label ?? candidate.origin,
      };
    }
  }
  return { ok: true };
}

/**
 * Convenience wrapper around `enforceModelAllowlist` that throws
 * `ModelNotAllowedError` on rejection. Use at write call sites so the server
 * adapter can translate into HTTP 422 + structured body.
 */
export function assertModelAllowed(allowed: ProviderModelEntry[] | undefined, input: ModelCandidateInput): void {
  const result = enforceModelAllowlist(allowed, input);
  if (result.ok) return;
  throw new ModelNotAllowedError({
    allowed,
    attempted: result.attempted,
    offendingLabel: result.offendingLabel,
  });
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add the requested model to the ProviderModelEntry allowlist configuration if it should be permitted
2. Have the client pick models from the server-provided allowlist instead of free-text input
3. Correct the model id/provider string to match an allowlisted entry exactly
4. Update cached model lists in the frontend after allowlist changes
5. Handle HTTP 422 ModelNotAllowedError responses by surfacing allowedModels from the structured body

Example fix

// before
assertModelAllowed(allowed, { modelId: 'gpt-5' }); // throws: not allowlisted
// after
assertModelAllowed(allowed, { modelId: 'gpt-4o' }); // allowlisted entry

function isAllowlisted(allowed: ProviderModelEntry[] | undefined, modelId: string): boolean {
  return !!allowed?.some(e => e.modelId === modelId);
}
if (!isAllowlisted(allowed, input.modelId)) throw new Error('Model not in allowlist');

function isAllowedModel(entry: ProviderModelEntry | undefined): entry is ProviderModelEntry {
  return entry !== undefined;
}

try {
  assertModelAllowed(allowed, candidate);
} catch (e) {
  if (e instanceof ModelNotAllowedError) {
    // return HTTP 422 with e.allowed so the client can pick a valid model
  }
}

When it happens

Trigger: Calling assertModelAllowed (from an agent-builder write endpoint) with a model id/provider string that is not present in the allowed ProviderModelEntry[] — e.g. requesting 'gpt-5' when the allowlist only contains 'gpt-4o', or an unparseable model string captured as offendingLabel.

Common situations: Client UIs sending stale model ids after the allowlist was tightened; new models released but not yet added to the allowlist; typo'd model identifiers; per-workspace allowlists differing from what the client cached.

Related errors

• error.message (422 res body includes attempted/offendingLabe
• Google user is not in an allowed hosted domain
• OAuth failed: ${tokenData.error}
• Root is not approved for rendered workspace access
• Session is not available to the current user

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