Skip to main content

​
Overview

Auth errors are thrown when authentication or authorization fails at the request level. These are public errors that inform clients about what action is needed (re-authenticate, authorize an app, etc.). For internal auth infrastructure errors, see Auth Internal Errors.

​
Error Reference

​
UnauthorizedError

Thrown when a request is missing valid credentials.
PropertyTypeValue
codestringUNAUTHORIZED
statusCodenumber401
isPublicbooleantrue
new UnauthorizedError(message?: string)
Example: 
import { UnauthorizedError } from '@frontmcp/sdk';

throw new UnauthorizedError('Bearer token expired');

​
AuthConfigurationError

Thrown when the authentication configuration is invalid (e.g., transparent mode on a parent with multiple child providers).
PropertyTypeValue
codestringAUTH_CONFIGURATION_ERROR
statusCodenumber500
isPublicbooleantrue
errorsstring[]List of configuration errors
suggestionstring | undefinedHow to fix the issue
new AuthConfigurationError(message: string, options?: {
  errors?: string[];
  suggestion?: string;
})
Example: 
import { AuthConfigurationError } from '@frontmcp/sdk';

throw new AuthConfigurationError('Invalid auth configuration', {
  errors: ['Transparent mode requires exactly one child provider'],
  suggestion: 'Set auth.mode to "local" or "remote" when using multiple providers.',
});

​
SessionMissingError

Thrown when a request arrives without a valid session. This tells the client it needs to authenticate.
PropertyTypeValue
codestringSESSION_MISSING
statusCodenumber401
isPublicbooleantrue
new SessionMissingError(message?: string)
Example: 
import { SessionMissingError } from '@frontmcp/sdk';

throw new SessionMissingError();
// "Unauthorized: missing session"

​
UnsupportedClientVersionError

Thrown when a client connects with an unsupported MCP protocol version.
PropertyTypeValue
codestringUNSUPPORTED_CLIENT_VERSION
statusCodenumber400
isPublicbooleantrue
clientVersionstringThe version string from the client
new UnsupportedClientVersionError(version: string)

// Factory method
UnsupportedClientVersionError.fromVersion(version: string)
Example: 
import { UnsupportedClientVersionError } from '@frontmcp/sdk';

throw UnsupportedClientVersionError.fromVersion('0.1.0');

​
AuthorizationRequiredError

Thrown when a tool requires app-level authorization the user has not yet granted. Supports progressive/incremental authorization. Behavior depends on session mode:
  • Stateful: Returns an auth_url link for incremental authorization
  • Stateless: Returns an unauthorized error (user must re-authenticate)
PropertyTypeValue
codestringAUTHORIZATION_REQUIRED
statusCodenumber403
isPublicbooleantrue
appIdstringApp requiring authorization
toolIdstringTool that triggered the requirement
authUrlstring | undefinedAuth URL (stateful mode only)
requiredScopesstring[] | undefinedScopes needed
sessionMode'stateful' | 'stateless'Session mode
supportsIncrementalbooleanWhether incremental auth is available
elicitIdstring | undefinedElicit flow ID
vaultIdstring | undefinedVault ID for stateful sessions
pendingAuthIdstring | undefinedTracking ID
new AuthorizationRequiredError(params: {
  appId: string;
  toolId: string;
  authUrl?: string;
  requiredScopes?: string[];
  message?: string;
  sessionMode?: 'stateful' | 'stateless';
  elicitId?: string;
  vaultId?: string;
  pendingAuthId?: string;
})
Methods:
MethodReturnsDescription
toMcpError()MCP error with _metaIncludes authorization metadata for AI agents
toAuthorizationRequiredData()AuthorizationRequiredDataStructured data object
toElicitResponse()ElicitResponse | nullElicit response (stateful only)
canUseIncrementalAuth()booleanWhether link-based auth is available
getUserFacingMessage()stringMessage with auth link or re-auth instructions
Example (stateful): 
import { AuthorizationRequiredError } from '@frontmcp/sdk';

throw new AuthorizationRequiredError({
  appId: 'slack',
  toolId: 'slack:send_message',
  authUrl: '/oauth/authorize?app=slack',
  sessionMode: 'stateful',
});
Example (stateless): 
throw new AuthorizationRequiredError({
  appId: 'slack',
  toolId: 'slack:send_message',
  sessionMode: 'stateless',
});

​
ToolNotAllowedError

Thrown when a tool is not in the active skill session’s allowlist. Used by the Tool Authorization Guard.
PropertyTypeValue
codestringTOOL_NOT_ALLOWED
statusCodenumber400
isPublicbooleantrue
toolNamestringThe denied tool name
skillIdstring | undefinedActive skill session ID
reasonstringnot_in_allowlist, denied, rate_limited, or no_active_skill
allowedToolsstring[]List of allowed tool names
import { ToolNotAllowedError } from '@frontmcp/sdk';

​
ToolApprovalRequiredError

Thrown when a tool requires explicit approval before use within a skill session (approval policy mode).
PropertyTypeValue
codestringTOOL_APPROVAL_REQUIRED
statusCodenumber400
isPublicbooleantrue
toolNamestringTool requiring approval
skillIdstring | undefinedActive skill session ID
import { ToolApprovalRequiredError } from '@frontmcp/sdk';