Class MtlsError

Represents an error that occurred during mTLS (Mutual TLS) configuration.

mTLS (RFC 8705) allows a confidential client to authenticate to Auth0 using a TLS client certificate instead of a client_secret or a signed JWT assertion. It also enables certificate-bound access tokens, which bind issued tokens cryptographically to the client certificate so that a stolen token cannot be replayed without the matching private key.

This error is thrown during Auth0Client construction when the mTLS configuration is invalid or incomplete.

Common scenarios that trigger MtlsError:

useMtls: true is set without providing a customFetch implementation
The authorization server discovery document lacks mtls_endpoint_aliases
useMtls: true is combined with clientSecret or clientAssertionSigningKey

Example: Handling mTLS configuration errors

import { Auth0Client } from "@auth0/nextjs-auth0/server";
import { MtlsError, MtlsErrorCode } from "@auth0/nextjs-auth0/errors";

try {
  const auth0 = new Auth0Client({
    useMtls: true,
    // customFetch omitted — will throw
  });
} catch (error) {
  if (error.code === MtlsErrorCode.MTLS_REQUIRES_CUSTOM_FETCH) {
    console.error("Provide a TLS-aware customFetch when useMtls is true.");
  }
}

Example: Providing a valid mTLS configuration (Node.js)

import { Agent, fetch as undiciFetch } from "undici";
import { Auth0Client } from "@auth0/nextjs-auth0/server";

const agent = new Agent({
  connect: {
    key: process.env.AUTH0_MTLS_CLIENT_KEY,
    cert: process.env.AUTH0_MTLS_CLIENT_CERT,
  },
});

const auth0 = new Auth0Client({
  useMtls: true,
  customFetch: (url, init) => undiciFetch(url, { ...init, dispatcher: agent }),
});

See

RFC 8705: OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens

Hierarchy (View Summary)

SdkError
- MtlsError

Index

Constructors

constructor

Properties

code

Constructors

constructor

new MtlsError(code: MtlsErrorCode, message: string): MtlsError
Constructs a new MtlsError instance.
Parameters
- code: MtlsErrorCode
  The mTLS error code indicating the specific type of failure
- message: string
  A descriptive error message explaining what went wrong
Returns MtlsError
Example
```
throw new MtlsError(
  MtlsErrorCode.MTLS_REQUIRES_CUSTOM_FETCH,
  "useMtls requires a customFetch option with a TLS client certificate."
);
```
Overrides SdkError.constructor
- Defined in src/errors/mtls-errors.ts:112

Properties

code

code: MtlsErrorCode

The specific mTLS error code indicating the type of failure.

Class MtlsError

Example: Handling mTLS configuration errors

Example: Providing a valid mTLS configuration (Node.js)

See

Hierarchy (View Summary)

Index

Constructors

Properties

Constructors

constructor

Parameters

Returns MtlsError

Example

Properties

code

Settings

On This Page