Note: configuration properties loaded from property files and environment variables are read once at startup and cached. Changes to property files or environment variables after MockServer has started will not take effect. To change configuration at runtime, use the REST API (PUT /mockserver/configuration) or programmatic ConfigurationProperties method calls. System property changes via ConfigurationProperties static methods are read dynamically for properties that support runtime changes (e.g., logLevel).
See also: Chaos Testing & Fault Injection for injecting errors, latency, and outages into mocked and proxied responses using declarative chaos profiles.
Properties can be set by:
@MockServerTest annotation (per-instance Configuration object)The order of precedence means that properties set by java code overrides those set by @MockServerTest which overrides system properties which overrides property file properties which overrides environment variables.
When using @MockServerTest, properties prefixed with mockserver. (e.g. mockserver.initializationClass=...) are applied to the per-instance Configuration object, not to global system properties. This makes them safe for parallel test execution.
Some properties need to be set before MockServer starts because they are only read at start-up, for example, nioEventLoopThreadCount.
Other values are read continuously and so can be changed at any time, for example, logLevel.
There are two ways to set properties programmatically, as follows:
The property file defaults to filename mockserver.properties in the current working directory of MockServer.
This location of the property file can be changed by setting the mockserver.propertyFile system property or MOCKSERVER_PROPERTY_FILE environment property, for example:
-Dmockserver.propertyFile=/config/mockserver.propertiesA full example / template properties file can be found in github
An limited properties file example is, as follows:
###############################
# MockServer & Proxy Settings #
###############################
# Socket & Port Settings
# socket timeout in milliseconds (default 20000)
mockserver.maxSocketTimeout=20000
# Certificate Generation
# dynamically generated CA key pair (if they don't already exist in specified directory)
mockserver.dynamicallyCreateCertificateAuthorityCertificate=true
# save dynamically generated CA key pair in working directory
mockserver.directoryToSaveDynamicSSLCertificate=.
# certificate domain name (default "localhost")
mockserver.sslCertificateDomainName=localhost
# comma separated list of ip addresses for Subject Alternative Name domain names (default empty list)
mockserver.sslSubjectAlternativeNameDomains=www.example.com,www.another.com
# comma separated list of ip addresses for Subject Alternative Name ips (default empty list)
mockserver.sslSubjectAlternativeNameIps=127.0.0.1
# CORS
# enable CORS for MockServer REST API
mockserver.enableCORSForAPI=true
# enable CORS for all responses
mockserver.enableCORSForAllResponses=trueMockServer also supports configuration via a JSON file. To use a JSON configuration file, set the mockserver.propertyFile system property or MOCKSERVER_PROPERTY_FILE environment variable to a file path ending with .json, for example:
-Dmockserver.propertyFile=/config/mockserver.jsonThe JSON format uses camelCase property names without the mockserver. prefix. An example JSON configuration file:
{
"logLevel": "INFO",
"maxSocketTimeout": 120000,
"dynamicallyCreateCertificateAuthorityCertificate": true,
"directoryToSaveDynamicSSLCertificate": ".",
"sslCertificateDomainName": "localhost",
"sslSubjectAlternativeNameDomains": ["www.example.com", "www.another.com"],
"sslSubjectAlternativeNameIps": ["127.0.0.1"],
"enableCORSForAPI": true,
"enableCORSForAllResponses": true
}The JSON property names are the camelCase equivalents of the mockserver.* property names listed below, with the mockserver. prefix removed. For example, mockserver.maxExpectations becomes maxExpectations in JSON. The complete list of supported JSON keys can be obtained by calling GET /mockserver/configuration, which returns all properties with their current values. This output can be saved as a JSON configuration file and reloaded at startup.
Maximum number of expectations held in the in-memory ring buffer. Expectations are stored in a circular queue so once this limit is reached the oldest and lowest priority expectations are overwritten.
Type: int Default: minimum of (free heap space in KB / 10) and 15000
The default is calculated automatically based on available JVM heap memory. Each expectation typically uses 4-10 KB of heap for small response bodies. Expectations with large response bodies use significantly more: a 10 KB response body results in ~15-20 KB per expectation, a 50 KB response body results in ~55-75 KB per expectation. With a 256 MB heap, the default is approximately 15,000. You can override this if you need more or want to reduce memory usage.
Power-of-2 sizing: the ring buffer is implemented on top of the LMAX Disruptor, which rounds the configured size up to the next power of 2. Setting maxExpectations=10000 actually allocates 16,384 slots (a 63.8% overhead). To minimise wasted heap, pick a power-of-2 value yourself: 1,024 / 2,048 / 4,096 / 8,192 / 16,384 / 32,768 / 65,536.
Java Code:
ConfigurationProperties.maxExpectations(int count)System Property:
-Dmockserver.maxExpectations=...Environment Variable:
MOCKSERVER_MAX_EXPECTATIONS=...Property File:
mockserver.maxExpectations=...Example:
-Dmockserver.maxExpectations="2000"Maximum number of log entries to hold in memory, this includes recorded requests, expectation match failures and other log entries. Log entries are stored in a circular queue so once this limit is reached the oldest entries are overwritten. The lower the log level the more log entries will be captured, particularly at TRACE level logging.
Type: int Default: minimum of (free heap space in KB / 8) and 100000
The default is calculated automatically based on available JVM heap memory. Each log entry typically uses 4-10 KB of heap for small request/response bodies, but log entries for large responses are proportionally larger (e.g., a 100 KB response body produces log entries of ~100+ KB each). Each HTTP request generates 2-3 log entries (request recording, expectation match, and response) that are always stored regardless of log level. With a 256 MB heap the default of approximately 20,000 entries covers around 7,000-10,000 HTTP requests before the oldest entries are evicted. For high-throughput use cases or large response bodies, reduce this value to limit memory usage and GC pressure. See troubleshooting performance for detailed guidance.
Power-of-2 sizing: the log ring buffer is implemented on top of the LMAX Disruptor, which rounds the configured size up to the next power of 2. Setting maxLogEntries=10000 allocates 16,384 slots; setting maxLogEntries=20000 allocates 32,768 slots. To minimise wasted heap, pick a power-of-2 value yourself: 4,096 (~32 MB) / 16,384 (~131 MB) / 65,536 (~524 MB) are good starting points.
Java Code:
ConfigurationProperties.maxLogEntries(int count)System Property:
-Dmockserver.maxLogEntries=...Environment Variable:
MOCKSERVER_MAX_LOG_ENTRIES=...Property File:
mockserver.maxLogEntries=...Example:
-Dmockserver.maxLogEntries="20000"Maximum number of remote (not the same JVM) method callbacks (i.e. web sockets) registered for expectations. The web socket client registry entries are stored in a circular queue so once this limit is reach the oldest are overwritten.
Type: int Default: 1500
Java Code:
ConfigurationProperties.maxWebSocketExpectations(int count)System Property:
-Dmockserver.maxWebSocketExpectations=...Environment Variable:
MOCKSERVER_MAX_WEB_SOCKET_EXPECTATIONS=...Property File:
mockserver.maxWebSocketExpectations=...Example:
-Dmockserver.maxWebSocketExpectations="2000"Output JVM memory usage metrics to CSV file periodically called memoryUsage_<yyyy-MM-dd>.csv
Type: boolean Default: false
Java Code:
ConfigurationProperties.outputMemoryUsageCsv(boolean enable)System Property:
-Dmockserver.outputMemoryUsageCsv=...Environment Variable:
MOCKSERVER_OUTPUT_MEMORY_USAGE_CSV=...Property File:
mockserver.outputMemoryUsageCsv=...Example:
-Dmockserver.outputMemoryUsageCsv="true"Directory to output JVM memory usage metrics CSV files to when outputMemoryUsageCsv enabled
Type: String Default: "."
Java Code:
ConfigurationProperties.memoryUsageCsvDirectory(String directory)System Property:
-Dmockserver.memoryUsageCsvDirectory=...Environment Variable:
MOCKSERVER_MEMORY_USAGE_CSV_DIRECTORY=...Property File:
mockserver.memoryUsageCsvDirectory=...Example:
-Dmockserver.memoryUsageCsvDirectory="."Experimental. UDP port for the experimental HTTP/3 (QUIC) listener. When set to a non-zero value MockServer starts an HTTP/3 server on this port in addition to the normal HTTP port(s); leave unset or 0 to disable (the default). Requires the BoringSSL/QUIC native library for the runtime platform. See HTTP/3 (QUIC) Support for details and current limitations.
Type: int Default: 0 (disabled)
Java Code:
ConfigurationProperties.http3Port(int port)System Property:
-Dmockserver.http3Port=...Environment Variable:
MOCKSERVER_HTTP3_PORT=...Property File:
mockserver.http3Port=...Example:
-Dmockserver.http3Port="1080"Maximum time in milliseconds allowed for a response from a socket
Type: long Default: 20000
Java Code:
ConfigurationProperties.maxSocketTimeout(long milliseconds)System Property:
-Dmockserver.maxSocketTimeout=...Environment Variable:
MOCKSERVER_MAX_SOCKET_TIMEOUT=...Property File:
mockserver.maxSocketTimeout=...Example:
-Dmockserver.maxSocketTimeout="10000"Maximum time in milliseconds allowed to connect to a socket
Type: long Default: 20000
Java Code:
ConfigurationProperties.socketConnectionTimeout(long milliseconds)System Property:
-Dmockserver.socketConnectionTimeout=...Environment Variable:
MOCKSERVER_SOCKET_CONNECTION_TIMEOUT=...Property File:
mockserver.socketConnectionTimeout=...Example:
-Dmockserver.socketConnectionTimeout="10000"If true socket connections will always be closed after a response is returned, if false connection is only closed if request header indicate connection should be closed.
Type: boolean Default: false
Java Code:
ConfigurationProperties.alwaysCloseSocketConnections(boolean alwaysClose)System Property:
-Dmockserver.alwaysCloseSocketConnections=...Environment Variable:
MOCKSERVER_ALWAYS_CLOSE_SOCKET_CONNECTIONS=...Property File:
mockserver.alwaysCloseSocketConnections=...Example:
-Dmockserver.alwaysCloseSocketConnections="true"The local IP address to bind to for accepting new socket connections
Type: string Default: 0.0.0.0
Java Code:
ConfigurationProperties.localBoundIP(String localBoundIP)System Property:
-Dmockserver.localBoundIP=...Environment Variable:
MOCKSERVER_LOCAL_BOUND_IP=...Property File:
mockserver.localBoundIP=...Example:
-Dmockserver.localBoundIP="0.0.0.0"Maximum size the first line of an HTTP request
Type: int Default: Integer.MAX_VALUE
Java Code:
ConfigurationProperties.maxInitialLineLength(int length)System Property:
-Dmockserver.maxInitialLineLength=...Environment Variable:
MOCKSERVER_MAX_INITIAL_LINE_LENGTH=...Property File:
mockserver.maxInitialLineLength=...Example:
-Dmockserver.maxInitialLineLength="8192"Maximum size HTTP request headers
Type: int Default: Integer.MAX_VALUE
Java Code:
ConfigurationProperties.maxHeaderSize(int size)System Property:
-Dmockserver.maxHeaderSize=...Environment Variable:
MOCKSERVER_MAX_HEADER_SIZE=...Property File:
mockserver.maxHeaderSize=...Example:
-Dmockserver.maxHeaderSize="16384"Maximum size of HTTP chunks in request or responses
Type: int Default: Integer.MAX_VALUE
Java Code:
ConfigurationProperties.maxChunkSize(int size)System Property:
-Dmockserver.maxChunkSize=...Environment Variable:
MOCKSERVER_MAX_CHUNK_SIZE=...Property File:
mockserver.maxChunkSize=...Example:
-Dmockserver.maxChunkSize="16384"Maximum aggregated body size (in bytes) accepted on inbound HTTP/1.1 and HTTP/2 requests. Requests larger than this are rejected — HTTP/1.1 clients typically receive a 413 Payload Too Large response, while HTTP/2 streams are reset. Bounding the inbound body protects MockServer from memory exhaustion when a misbehaving or malicious client uploads an extremely large payload.
Type: int Default: 10485760 (10 MiB)
Raise this only if you intentionally mock large uploads. Very large limits make MockServer susceptible to OOM when many concurrent uploads arrive.
Java Code:
ConfigurationProperties.maxRequestBodySize(int size)System Property:
-Dmockserver.maxRequestBodySize=...Environment Variable:
MOCKSERVER_MAX_REQUEST_BODY_SIZE=...Property File:
mockserver.maxRequestBodySize=...Example:
-Dmockserver.maxRequestBodySize="52428800"Maximum aggregated body size (in bytes) accepted on responses received from upstream servers when MockServer is acting as a proxy or forwarder.
Type: int Default: 52428800 (50 MiB)
Java Code:
ConfigurationProperties.maxResponseBodySize(int size)System Property:
-Dmockserver.maxResponseBodySize=...Environment Variable:
MOCKSERVER_MAX_RESPONSE_BODY_SIZE=...Property File:
mockserver.maxResponseBodySize=...Example:
-Dmockserver.maxResponseBodySize="104857600"Maximum time (in milliseconds) allowed for evaluating a single regular expression during request matching. A pathological pattern (e.g. (a+)+b) that exceeds this budget is treated as a non-match and a WARN log entry is written, so the server cannot be wedged by exponential regex backtracking from a malicious expectation or input. Set to 0 or a negative value to disable the timeout.
Performance note: the timeout is enforced by evaluating each regular expression on a shared executor and waiting for the result, which adds a thread hand-off per regex, per matcher, per request. Setting this to 0 runs regex evaluation inline on the request thread, removing that hand-off — a measurable speed-up for matchers that evaluate many regular expressions per request. Only do this when your expectations and request inputs use trusted, non-pathological patterns, because it also removes the backtracking guard (a single catastrophic pattern can then block a worker thread). This is a global switch; there is intentionally no per-pattern “inline this one” option, as even a short pattern can backtrack catastrophically.
Type: long Default: 5000
Java Code:
ConfigurationProperties.regexMatchingTimeoutMillis(long milliseconds)System Property:
-Dmockserver.regexMatchingTimeoutMillis=...Environment Variable:
MOCKSERVER_REGEX_MATCHING_TIMEOUT_MILLIS=...Property File:
mockserver.regexMatchingTimeoutMillis=...Example:
-Dmockserver.regexMatchingTimeoutMillis="2000"Maximum time (in milliseconds) allowed for evaluating a single XPath expression against an XML document during request matching. Exceeding this budget is treated as a non-match and a WARN log entry is written, protecting MockServer from XPath-based denial-of-service. Set to 0 or a negative value to disable the timeout.
Type: long Default: 5000
Java Code:
ConfigurationProperties.xpathMatchingTimeoutMillis(long milliseconds)System Property:
-Dmockserver.xpathMatchingTimeoutMillis=...Environment Variable:
MOCKSERVER_XPATH_MATCHING_TIMEOUT_MILLIS=...Property File:
mockserver.xpathMatchingTimeoutMillis=...Example:
-Dmockserver.xpathMatchingTimeoutMillis="2000"Fully qualified name of a class that registers custom json-unit matchers, so JSON body expectations can validate dynamic values (e.g. "price must be greater than 100") with the ${json-unit.matches:name} placeholder.
The class must have a public no-arg constructor and implement org.mockserver.matchers.CustomJsonUnitMatcherProvider, returning a Map<String, org.hamcrest.Matcher<?>> keyed by the placeholder name. If the class cannot be loaded, does not implement the interface, or its constructor throws, MockServer logs a WARN and JSON matching falls back to its built-in behaviour.
Type: string Default: "" (no custom matchers)
Example provider:
public class MyJsonUnitMatchers implements CustomJsonUnitMatcherProvider {
public Map<String, Matcher<?>> jsonUnitMatchers() {
Map<String, Matcher<?>> matchers = new HashMap<>();
matchers.put("largerThan", new BaseMatcher<Object>() {
public boolean matches(Object actual) {
return new BigDecimal(actual.toString()).compareTo(BigDecimal.valueOf(100)) > 0;
}
public void describeTo(Description d) { d.appendText("a number larger than 100"); }
});
return matchers;
}
}Then reference the matcher from the JSON body of an expectation:
{ "price": "${json-unit.matches:largerThan}" }Java Code:
ConfigurationProperties.customJsonUnitMatchersClass(String className)System Property:
-Dmockserver.customJsonUnitMatchersClass=...Environment Variable:
MOCKSERVER_CUSTOM_JSON_UNIT_MATCHERS_CLASS=...Property File:
mockserver.customJsonUnitMatchersClass=...Example:
-Dmockserver.customJsonUnitMatchersClass="com.example.MyJsonUnitMatchers"When enabled, MockServer rejects forward and proxy targets that resolve to loopback, link-local, RFC 1918 private, or cloud metadata addresses (such as 169.254.169.254). This blocks server-side request forgery (SSRF) attacks where a malicious expectation would otherwise forward through MockServer to internal infrastructure.
Type: boolean Default: false
The default is false because MockServer is most commonly used to mock services running on localhost, Docker bridge networks, or Kubernetes service IPs — blocking those by default would break the common case. Enable this in hardened or multi-tenant deployments where untrusted callers can register expectations.
Java Code:
ConfigurationProperties.forwardProxyBlockPrivateNetworks(boolean block)System Property:
-Dmockserver.forwardProxyBlockPrivateNetworks=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_BLOCK_PRIVATE_NETWORKS=...Property File:
mockserver.forwardProxyBlockPrivateNetworks=...Example:
-Dmockserver.forwardProxyBlockPrivateNetworks="true"Whether to honour TLSv1 and TLSv1.1 in tlsProtocols. Both protocols are deprecated by RFC 8996 and vulnerable to BEAST and POODLE.
Type: boolean Default: true
The default is true for backwards compatibility — MockServer's tlsProtocols default still includes TLSv1 and TLSv1.1. Set this to false to opt into a hardened profile: any TLSv1 or TLSv1.1 entries in tlsProtocols are filtered out before the SSL context is built. A future major release is expected to flip this default to false.
Java Code:
ConfigurationProperties.tlsAllowInsecureProtocols(boolean allow)System Property:
-Dmockserver.tlsAllowInsecureProtocols=...Environment Variable:
MOCKSERVER_TLS_ALLOW_INSECURE_PROTOCOLS=...Property File:
mockserver.tlsAllowInsecureProtocols=...Example:
-Dmockserver.tlsAllowInsecureProtocols="false"If true semicolons are treated as a separator for a query parameter string, if false the semicolon is treated as a normal character that is part of a query parameter value.
Type: boolean Default: true
Java Code:
ConfigurationProperties.useSemicolonAsQueryParameterSeparator(boolean useSemicolonAsQueryParameterSeparator)System Property:
-Dmockserver.useSemicolonAsQueryParameterSeparator=...Environment Variable:
MOCKSERVER_USE_SEMICOLON_AS_QUERY_PARAMETER_SEPARATOR=...Property File:
mockserver.useSemicolonAsQueryParameterSeparator=...Example:
-Dmockserver.useSemicolonAsQueryParameterSeparator="false"If false requests are assumed as binary if the method isn't one of "GET", "POST", "PUT", "HEAD", "OPTIONS", "PATCH", "DELETE", "TRACE" or "CONNECT"
Type: boolean Default: false
Java Code:
ConfigurationProperties.assumeAllRequestsAreHttp(boolean assumeAllRequestsAreHttp)System Property:
-Dmockserver.assumeAllRequestsAreHttp=...Environment Variable:
MOCKSERVER_ASSUME_ALL_REQUESTS_ARE_HTTP=...Property File:
mockserver.assumeAllRequestsAreHttp=...Example:
-Dmockserver.assumeAllRequestsAreHttp="true"If false HTTP/2 is disabled so MockServer no longer advertises h2 during TLS ALPN negotiation (and does not detect the HTTP/2 cleartext h2c upgrade). HTTP/2 capable clients then fall back to HTTP/1.1, which is useful for testing how a client behaves over HTTP/1.1 without changing the client itself.
Type: boolean Default: true
Java Code:
ConfigurationProperties.http2Enabled(boolean http2Enabled)System Property:
-Dmockserver.http2Enabled=...Environment Variable:
MOCKSERVER_HTTP2_ENABLED=...Property File:
mockserver.http2Enabled=...Example:
-Dmockserver.http2Enabled="false"Note: HTTP/2 proxying has limitations. When MockServer forwards requests to downstream services, HTTP/2 requests are downgraded to HTTP/1.1. MockServer can accept HTTP/2 connections and serve mock responses over HTTP/2, but forwarded/proxied requests are always sent as HTTP/1.1. See HTTP/2 proxy limitations for details.
If true (the default) when no matching expectation is found, and the host header of the request does not match MockServer's host, then MockServer attempts to proxy the request. If the upstream server is unreachable (connection refused, TLS error, timeout, etc.) a 502 Bad Gateway is returned. If no matching expectation is found and the request is not eligible for proxying, a 404 is returned.
If false when no matching expectation is found, and MockServer is not being used as a proxy, then MockServer always returns a 404 immediately.
Note: this property only triggers proxy behaviour when the Host header in the request differs from MockServer's own local addresses (e.g., localhost, 127.0.0.1, or the machine's hostname). If the Host header matches MockServer's address, the request is not forwarded regardless of this setting. In Docker, set this via environment variable: MOCKSERVER_ATTEMPT_TO_PROXY_IF_NO_MATCHING_EXPECTATION=true.
Type: boolean Default: true
Java Code:
ConfigurationProperties.attemptToProxyIfNoMatchingExpectation(boolean enable)System Property:
-Dmockserver.attemptToProxyIfNoMatchingExpectation=...Environment Variable:
MOCKSERVER_ATTEMPT_TO_PROXY_IF_NO_MATCHING_EXPECTATION=...Property File:
mockserver.attemptToProxyIfNoMatchingExpectation=...Example:
-Dmockserver.attemptToProxyIfNoMatchingExpectation="false"Use HTTP proxy (i.e. via Host header) for all outbound / forwarded requests
Type: string Default: null
Java Code:
ConfigurationProperties.forwardHttpProxy(String hostAndPort)System Property:
-Dmockserver.forwardHttpProxy=...Environment Variable:
MOCKSERVER_FORWARD_HTTP_PROXY=...Property File:
mockserver.forwardHttpProxy=...Example:
-Dmockserver.forwardHttpProxy="127.0.0.1:1090"Use HTTPS proxy (i.e. HTTP CONNECT) for all outbound / forwarded requests, supports TLS tunnelling of HTTPS requests
Type: string Default: null
Java Code:
ConfigurationProperties.forwardHttpsProxy(String hostAndPort)System Property:
-Dmockserver.forwardHttpsProxy=...Environment Variable:
MOCKSERVER_FORWARD_HTTPS_PROXY=...Property File:
mockserver.forwardHttpsProxy=...Example:
-Dmockserver.forwardHttpsProxy="127.0.0.1:1090"Use SOCKS proxy for all outbound / forwarded requests, support TLS tunnelling of TCP connections
Type: string Default: null
Java Code:
ConfigurationProperties.forwardSocksProxy(String hostAndPort)System Property:
-Dmockserver.forwardSocksProxy=...Environment Variable:
MOCKSERVER_FORWARD_SOCKS_PROXY=...Property File:
mockserver.forwardSocksProxy=...Example:
-Dmockserver.forwardSocksProxy="127.0.0.1:1090"Username for proxy authentication when using HTTPS proxy (i.e. HTTP CONNECT) for all outbound / forwarded requests
Note: 8u111 Update Release Notes state that the Basic authentication scheme has been deactivated when setting up an HTTPS tunnel. To resolve this clear or set to an empty string the following system properties: jdk.http.auth.tunneling.disabledSchemes and jdk.http.auth.proxying.disabledSchemes.
Type: string Default: null
Java Code:
ConfigurationProperties.forwardProxyAuthenticationUsername(String forwardProxyAuthenticationUsername)System Property:
-Dmockserver.forwardProxyAuthenticationUsername=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_AUTHENTICATION_USERNAME=...Property File:
mockserver.forwardProxyAuthenticationUsername=...Example:
-Dmockserver.forwardProxyAuthenticationUsername=john.doePassword for proxy authentication when using HTTPS proxy (i.e. HTTP CONNECT) for all outbound / forwarded requests
Note: 8u111 Update Release Notes state that the Basic authentication scheme has been deactivated when setting up an HTTPS tunnel. To resolve this clear or set to an empty string the following system properties: jdk.http.auth.tunneling.disabledSchemes and jdk.http.auth.proxying.disabledSchemes.
Type: string Default: null
Java Code:
ConfigurationProperties.forwardProxyAuthenticationPassword(String forwardProxyAuthenticationPassword)System Property:
-Dmockserver.forwardProxyAuthenticationPassword=...Environment Variable:
MOCKSERVER_FORWARD_PROXY_AUTHENTICATION_PASSWORD=...Property File:
mockserver.forwardProxyAuthenticationPassword=...Example:
-Dmockserver.forwardProxyAuthenticationPassword="p@ssw0rd"The authentication realm for proxy authentication to MockServer
Type: string Default: MockServer HTTP Proxy
Java Code:
ConfigurationProperties.proxyAuthenticationRealm(String proxyAuthenticationRealm)System Property:
-Dmockserver.proxyAuthenticationRealm=...Environment Variable:
MOCKSERVER_PROXY_SERVER_REALM=...Property File:
mockserver.proxyAuthenticationRealm=...Example:
-Dmockserver.proxyAuthenticationRealm="MockServer HTTP Proxy"The required username for proxy authentication to MockServer
Note: 8u111 Update Release Notes state that the Basic authentication scheme has been deactivated when setting up an HTTPS tunnel. To resolve this clear or set to an empty string the following system properties: jdk.http.auth.tunneling.disabledSchemes and jdk.http.auth.proxying.disabledSchemes.
Type: string Default:
Java Code:
ConfigurationProperties.proxyAuthenticationUsername(String proxyAuthenticationUsername)System Property:
-Dmockserver.proxyAuthenticationUsername=...Environment Variable:
MOCKSERVER_PROXY_AUTHENTICATION_USERNAME=...Property File:
mockserver.proxyAuthenticationUsername=...Example:
-Dmockserver.proxyAuthenticationUsername=john.doeThe required password for proxy authentication to MockServer
Note: 8u111 Update Release Notes state that the Basic authentication scheme has been deactivated when setting up an HTTPS tunnel. To resolve this clear or set to an empty string the following system properties: jdk.http.auth.tunneling.disabledSchemes and jdk.http.auth.proxying.disabledSchemes.
Type: string Default:
Java Code:
ConfigurationProperties.proxyAuthenticationPassword(String proxyAuthenticationPassword)System Property:
-Dmockserver.proxyAuthenticationPassword=...Environment Variable:
MOCKSERVER_PROXY_AUTHENTICATION_PASSWORD=...Property File:
mockserver.proxyAuthenticationPassword=...Example:
-Dmockserver.proxyAuthenticationPassword="p@ssw0rd"Configure reverse proxy mappings that route incoming requests by path prefix to upstream servers with automatic path rewriting. This provides Apache-style ProxyPass functionality.
Value is a JSON array of objects. Each object has:
Path rewriting example: with pathPrefix="/api/" and targetUri="https://backend:8443/services/", a request to GET /api/users/123 is forwarded as GET /services/users/123 to backend:8443 over HTTPS.
Mappings are evaluated in order; the first matching prefix wins. ProxyPass is evaluated after expectations and CORS, but before the speculative proxy attempt.
Type: JSON array Default: []
Java Code:
ConfigurationProperties.proxyPass("[{\"pathPrefix\":\"/api/\",\"targetUri\":\"https://backend:8443/services/\"}]")System Property:
-Dmockserver.proxyPass=...Environment Variable:
MOCKSERVER_PROXY_PASS=...Property File:
mockserver.proxyPass=[{"pathPrefix":"/api/","targetUri":"https://backend:8443/services/"}]Example:
MOCKSERVER_PROXY_PASS='[{"pathPrefix":"/api/","targetUri":"https://backend:8443/services/"},{"pathPrefix":"/auth/","targetUri":"http://auth-server:9090/","preserveHost":true}]'Comma-separated list of hostnames that MockServer should not proxy to. When a request's Host header matches one of these hosts, MockServer will return a 404 instead of forwarding the request. This applies both to direct proxying and to upstream proxy bypass.
Supports exact hostnames (e.g. example.com), wildcard prefixes (e.g. *.internal.corp), and IP addresses (e.g. 192.168.1.1).
Type: string Default: ""
Java Code:
ConfigurationProperties.noProxyHosts(String noProxyHosts)System Property:
-Dmockserver.noProxyHosts=...Environment Variable:
MOCKSERVER_NO_PROXY_HOSTS=...Property File:
mockserver.noProxyHosts=...Example:
-Dmockserver.noProxyHosts="*.internal.corp,localhost,192.168.1.1"If true (the default) the Host header will be automatically adjusted to match the target server when forwarding requests via HttpOverrideForwardedRequest or template-based forwards. This prevents HTTP 421 Misdirected Request errors when the target server validates Host headers.
If false the original Host header is preserved unless explicitly overridden in the request override.
Note: When an explicit Host header is provided in the request override, it is always preserved regardless of this setting. Similarly, when a template explicitly sets the Host header to a value different from the original request, it is preserved. Header changes made via requestModifier are still subject to auto-adjustment. This setting only applies when the Host header is not explicitly overridden and a socketAddress is specified for routing.
Type: boolean Default: true
Java Code:
ConfigurationProperties.forwardAdjustHostHeader(boolean enable)System Property:
-Dmockserver.forwardAdjustHostHeader=...Environment Variable:
MOCKSERVER_FORWARD_ADJUST_HOST_HEADER=...Property File:
mockserver.forwardAdjustHostHeader=...Example:
-Dmockserver.forwardAdjustHostHeader="false"Set a default Host header value to use when forwarding requests. When set, the Host header will be overridden with this value for all forwarded requests, regardless of the target server's address. This is useful when the target proxy server routes requests based on the Host header.
Type: string Default: null
Java Code:
ConfigurationProperties.forwardDefaultHostHeader(String hostHeader)System Property:
-Dmockserver.forwardDefaultHostHeader=...Environment Variable:
MOCKSERVER_FORWARD_DEFAULT_HOST_HEADER=...Property File:
mockserver.forwardDefaultHostHeader=...Example:
-Dmockserver.forwardDefaultHostHeader="foo.com"The hostname of the remote server to forward all unmatched requests to. When set together with proxyRemotePort, MockServer acts as a forward proxy, sending any request that does not match an expectation to the specified remote host. The Host header is automatically updated to match the configured remote host unless forwardDefaultHostHeader is set. This works in all deployment modes including WAR deployments.
Type: string Default: "" (unset)
Java Code:
ConfigurationProperties.proxyRemoteHost(String hostname)System Property:
-Dmockserver.proxyRemoteHost=...Environment Variable:
MOCKSERVER_PROXY_REMOTE_HOST=...Property File:
mockserver.proxyRemoteHost=...Example:
-Dmockserver.proxyRemoteHost="www.mock-server.com"The port of the remote server to forward all unmatched requests to. Must be specified together with proxyRemoteHost. Valid values are 1-65535.
Type: integer Default: null
Java Code:
ConfigurationProperties.proxyRemotePort(Integer port)System Property:
-Dmockserver.proxyRemotePort=...Environment Variable:
MOCKSERVER_PROXY_REMOTE_PORT=...Property File:
mockserver.proxyRemotePort=...Example:
-Dmockserver.proxyRemotePort="443"These properties control how MockServer handles streaming responses (Server-Sent Events with Content-Type: text/event-stream) when acting as a proxy. This is particularly relevant when proxying LLM API traffic from AI coding agents. See Inspect AI Agent Traffic for a full usage guide.
If true (the default) streaming responses (Server-Sent Events with Content-Type: text/event-stream) received while proxying are relayed to the client incrementally as they arrive, instead of being fully buffered before being forwarded. This keeps streaming APIs such as LLM APIs (Anthropic, OpenAI) responsive when proxied. Streaming is auto-detected from the Content-Type response header and does not affect non-streaming responses. Ordinary chunked responses (without text/event-stream) are always aggregated normally.
Set to false to revert to the previous behaviour of fully buffering every proxied response before forwarding it.
Type: boolean Default: true
Java Code:
ConfigurationProperties.streamingResponsesEnabled(boolean enable)System Property:
-Dmockserver.streamingResponsesEnabled=...Environment Variable:
MOCKSERVER_STREAMING_RESPONSES_ENABLED=...Property File:
mockserver.streamingResponsesEnabled=...Example:
-Dmockserver.streamingResponsesEnabled="false"The maximum number of bytes of a streaming response body captured into the event log while relaying it. The full stream is always relayed to the client; this only bounds how much is retained for the dashboard Traffic Inspector and the retrieve API. Once this limit is exceeded, the logged body is truncated and the response is flagged with x-mockserver-stream-truncated: true. Increase this value if you need to capture full LLM completions longer than 256 KB.
Type: int Default: 262144 (256 KB)
Java Code:
ConfigurationProperties.maxStreamingCaptureBytes(int bytes)System Property:
-Dmockserver.maxStreamingCaptureBytes=...Environment Variable:
MOCKSERVER_MAX_STREAMING_CAPTURE_BYTES=...Property File:
mockserver.maxStreamingCaptureBytes=...Example:
-Dmockserver.maxStreamingCaptureBytes="524288"The maximum inbound request body size (in bytes) that LLM conversation-aware matchers will parse when evaluating predicates such as whenLatestMessageContains or whenContainsToolResultFor. Requests larger than this value skip conversation-aware parsing entirely and are treated as no-match by those predicates, which protects the matcher from crafted JSON inputs designed to consume CPU or memory. Values outside the supported range are clamped at startup.
Type: int Default: 1048576 (1 MiB) Range: [16384, 67108864] (16 KiB – 64 MiB)
Java Code:
ConfigurationProperties.maxLlmConversationBodySize(int bytes)System Property:
-Dmockserver.maxLlmConversationBodySize=...Environment Variable:
MOCKSERVER_MAX_LLM_CONVERSATION_BODY_SIZE=...Property File:
mockserver.maxLlmConversationBodySize=...Example:
-Dmockserver.maxLlmConversationBodySize="2097152"Some optional LLM features need MockServer to call a real LLM you already run — for example drift detection (replaying recorded fixtures against the live provider) and exploratory semantic prompt matching. These features are off unless a backend is configured, and they fail closed: if a configured backend times out or errors, the feature behaves exactly as if it were unconfigured and logs a single line. A real LLM call is never placed on the deterministic assertion/matching path.
A backend can be supplied three ways (simplest first):
Supported providers reuse the existing provider list: Anthropic, OpenAI, OpenAI Responses, Gemini, Azure OpenAI, Ollama, and Bedrock. Ollama is the easiest to start with — it needs no key and runs locally. The API key is a secret and is redacted (***) anywhere configuration is logged.
Type: String Default: unset (runtime-LLM features disabled)
Java Code:
ConfigurationProperties.llmProvider(String provider)
ConfigurationProperties.llmApiKey(String apiKey)
ConfigurationProperties.llmModel(String model)
ConfigurationProperties.llmBaseUrl(String baseUrl)
ConfigurationProperties.llmBackendsConfig(String jsonFilePath)
ConfigurationProperties.llmRequestTimeoutMillis(long millis)System Property:
-Dmockserver.llmProvider=... -Dmockserver.llmApiKey=... -Dmockserver.llmModel=... -Dmockserver.llmBaseUrl=... -Dmockserver.llmBackendsConfig=... -Dmockserver.llmRequestTimeoutMillis=...Environment Variable:
MOCKSERVER_LLM_PROVIDER=... MOCKSERVER_LLM_API_KEY=... MOCKSERVER_LLM_MODEL=... MOCKSERVER_LLM_BASE_URL=... MOCKSERVER_LLM_BACKENDS_CONFIG=... MOCKSERVER_LLM_REQUEST_TIMEOUT_MILLIS=...Property File:
mockserver.llmProvider=OLLAMA
mockserver.llmRequestTimeoutMillis=30000Example (OpenAI default backend):
-Dmockserver.llmProvider="OPENAI" -Dmockserver.llmApiKey="sk-..."Exploratory semantic matching — opt in to the fuzzy, LLM-judged semanticMatch conversation predicate. Off by default and ignored unless a backend (above) also resolves. It calls a live model to judge intent, so it is non-deterministic and must never gate a CI assertion — use it for exploration only. Type: boolean Default: false
ConfigurationProperties.llmSemanticMatchingEnabled(boolean enabled)-Dmockserver.llmSemanticMatchingEnabled=... MOCKSERVER_LLM_SEMANTIC_MATCHING_ENABLED=...Controls for recording LLM/MCP traffic to committable fixture files and replaying it deterministically (see the record_llm_fixtures and load_expectations_from_file MCP tools).
Body field redaction — comma-separated JSON field names whose values are redacted from recorded request/response bodies, in addition to the always-redacted sensitive headers. Empty by default.
Type: String Default: unset
Java Code:
ConfigurationProperties.fixtureBodyRedactFields(String commaSeparatedFields)System Property:
-Dmockserver.fixtureBodyRedactFields=...Environment Variable:
MOCKSERVER_FIXTURE_BODY_REDACT_FIELDS=...Example:
-Dmockserver.fixtureBodyRedactFields="api_key,password,token"Strict VCR mode — when true, loading a fixture registers a low-priority catch-all per cassette path so a request matching no recorded entry returns HTTP 599 rather than falling through. Useful for catching un-recorded calls in tests. Default false (can also be set per call via the load_expectations_from_file strict parameter).
Type: boolean Default: false
Java Code:
ConfigurationProperties.llmVcrStrict(boolean strict)System Property:
-Dmockserver.llmVcrStrict=...Environment Variable:
MOCKSERVER_LLM_VCR_STRICT=...Example:
-Dmockserver.llmVcrStrict="true"Controls for mock drift detection and semantic drift analysis. See Drift Detection for full details.
Semantic drift analysis — when true and a runtime LLM backend is configured, each structural drift record is enriched with an LLM-classified severity (BREAKING, WARNING, or INFORMATIONAL) and a one-sentence explanation. Off by default (opt-in). Enrichment is best-effort: if the LLM is unavailable, drift records are stored with structural data only.
Type: boolean Default: false
Java Code:
ConfigurationProperties.driftSemanticAnalysisEnabled(boolean enabled)System Property:
-Dmockserver.driftSemanticAnalysisEnabled=...Environment Variable:
MOCKSERVER_DRIFT_SEMANTIC_ANALYSIS_ENABLED=...Example:
-Dmockserver.driftSemanticAnalysisEnabled="true"Performance drift threshold — p95 response time threshold in milliseconds. When set to a positive value, a PERFORMANCE drift record is emitted whenever the p95 response time for an expectation exceeds this threshold. MockServer tracks the last 100 response times per expectation in a sliding window. Set to 0 to disable.
Type: long Default: 0 (disabled)
Java Code:
ConfigurationProperties.driftResponseTimeThresholdMs(long thresholdMs)System Property:
-Dmockserver.driftResponseTimeThresholdMs=...Environment Variable:
MOCKSERVER_DRIFT_RESPONSE_TIME_THRESHOLD_MS=...Example:
-Dmockserver.driftResponseTimeThresholdMs="500"MockServer can export to an OpenTelemetry (OTLP) collector, in two independent parts that are each off by default and fail-soft (a startup error logs one line and never stops the server or affects a response). Both use the OTLP HTTP/protobuf exporter with the JDK HTTP client (no gRPC/OkHttp) and share the same endpoint.
1. Metrics export — push MockServer's explicitly-defined metrics (request counts, expectation-match counts, action counts including the LLM and chaos counters) to OTLP, as an alternative to the Prometheus endpoint. Implemented as observable gauges reading the current values, so the Prometheus and OTLP views stay consistent. It does not add tracing or automatic instrumentation.
Type: boolean Default: false
ConfigurationProperties.otelMetricsEnabled(boolean enabled)-Dmockserver.otelMetricsEnabled=... MOCKSERVER_OTEL_METRICS_ENABLED=...Export interval (seconds), default 60:
-Dmockserver.otelMetricsExportIntervalSeconds=... MOCKSERVER_OTEL_METRICS_EXPORT_INTERVAL_SECONDS=...2. GenAI span export — emit one OpenTelemetry GenAI semantic-convention span per LLM completion MockServer serves, carrying provider (gen_ai.system), model, token usage and finish reason. These are spans MockServer codes deliberately — no auto-instrumentation is added.
Type: boolean Default: false
ConfigurationProperties.otelTracesEnabled(boolean enabled)-Dmockserver.otelTracesEnabled=... MOCKSERVER_OTEL_TRACES_ENABLED=...OTLP endpoint (shared) — the collector base URL (e.g. http://localhost:4318); the /v1/metrics and /v1/traces paths are appended per signal. Empty uses the OTLP default (http://localhost:4318).
ConfigurationProperties.otelEndpoint(String baseUrl)-Dmockserver.otelEndpoint=... MOCKSERVER_OTEL_ENDPOINT=...Example (both signals to a collector):
-Dmockserver.otelMetricsEnabled="true" -Dmockserver.otelTracesEnabled="true" -Dmockserver.otelEndpoint="http://otel-collector:4318"3. W3C Trace Context propagation — extract the W3C traceparent and tracestate headers from incoming requests and optionally copy them to mock responses. This lets callers correlate request-response pairs within a distributed trace when MockServer sits in a service mesh or test harness. The handler is always present in the pipeline but is a no-op unless enabled.
Propagate trace context to responses — when enabled, the traceparent (and tracestate, if present) headers from the incoming request are added to the mock response.
Type: boolean Default: false
ConfigurationProperties.otelPropagateTraceContext(boolean enabled)-Dmockserver.otelPropagateTraceContext=... MOCKSERVER_OTEL_PROPAGATE_TRACE_CONTEXT=...Generate trace ID — when enabled, MockServer generates a new random W3C trace ID for incoming requests that do not carry a traceparent header. Useful for test harnesses that want every request to have a trace context.
Type: boolean Default: false
ConfigurationProperties.otelGenerateTraceId(boolean enabled)-Dmockserver.otelGenerateTraceId=... MOCKSERVER_OTEL_GENERATE_TRACE_ID=...Example (propagate trace context and generate IDs for untraced requests):
-Dmockserver.otelPropagateTraceContext="true" -Dmockserver.otelGenerateTraceId="true"The maximum time in seconds a streaming response connection may be idle (no chunk received from the upstream server) before MockServer closes it and logs the captured portion as truncated. This replaces the fixed global socket timeout for streaming responses, which would otherwise terminate long-lived LLM completions. The timeout resets on every chunk received, so a slow-but-active stream is never cut off prematurely.
Type: int Default: 60 (seconds)
Java Code:
ConfigurationProperties.streamIdleTimeoutSeconds(int seconds)System Property:
-Dmockserver.streamIdleTimeoutSeconds=...Environment Variable:
MOCKSERVER_STREAM_IDLE_TIMEOUT_SECONDS=...Property File:
mockserver.streamIdleTimeoutSeconds=...Example:
-Dmockserver.streamIdleTimeoutSeconds="120"Adds a fixed delay (in milliseconds) to all matched expectation responses. This delay is additive — it combines with any per-action delay configured on individual expectations. For example, if an expectation has a 100ms delay and the global delay is 200ms, the total delay is 300ms.
This is useful for simulating network latency across all mocked endpoints without having to configure delay on each expectation individually.
Type: long Default: null (no global delay)
Java Code:
ConfigurationProperties.globalResponseDelayMillis(Long millis)System Property:
-Dmockserver.globalResponseDelayMillis=...Environment Variable:
MOCKSERVER_GLOBAL_RESPONSE_DELAY_MILLIS=...Property File:
mockserver.globalResponseDelayMillis=...Example:
-Dmockserver.globalResponseDelayMillis="200"Path to support HTTP GET requests for status response (also available on PUT /mockserver/status).
If this value is not modified then only PUT /mockserver/status but is a none blank value is provided for this value then GET requests to this path will return the 200 Ok status response showing the MockServer version and bound ports.
A GET request to this path will be matched before any expectation matching or proxying of requests.
Type: string Default: null
Java Code:
ConfigurationProperties.livenessHttpGetPath(String livenessPath)System Property:
-Dmockserver.livenessHttpGetPath=...Environment Variable:
MOCKSERVER_LIVENESS_HTTP_GET_PATH=...Property File:
mockserver.livenessHttpGetPath=...Example:
-Dmockserver.livenessHttpGetPath="/liveness/probe"These properties configure server-wide defaults for AsyncAPI broker mocking. Per-request brokerConfig values in the PUT /mockserver/asyncapi request body override these defaults.
Default Kafka bootstrap servers used when a PUT /mockserver/asyncapi request body does not include brokerConfig.kafkaBootstrapServers. When unset (empty string), the broker must be specified per-request.
Type: string Default: "" (unset)
Java Code:
ConfigurationProperties.asyncKafkaBootstrapServers(String servers)System Property:
-Dmockserver.asyncKafkaBootstrapServers=...Environment Variable:
MOCKSERVER_ASYNC_KAFKA_BOOTSTRAP_SERVERS=...Property File:
mockserver.asyncKafkaBootstrapServers=...Example:
-Dmockserver.asyncKafkaBootstrapServers="localhost:9092"Default MQTT broker URL used when a PUT /mockserver/asyncapi request body does not include brokerConfig.mqttBrokerUrl. When unset (empty string), the broker must be specified per-request.
Type: string Default: "" (unset)
Java Code:
ConfigurationProperties.asyncMqttBrokerUrl(String url)System Property:
-Dmockserver.asyncMqttBrokerUrl=...Environment Variable:
MOCKSERVER_ASYNC_MQTT_BROKER_URL=...Property File:
mockserver.asyncMqttBrokerUrl=...Example:
-Dmockserver.asyncMqttBrokerUrl="tcp://localhost:1883"Maximum number of recorded messages retained per channel in async messaging subscribers. When the cap is reached, the oldest messages are evicted (FIFO). This prevents unbounded memory growth when consuming high-volume topics.
Type: int Default: 1000
Java Code:
ConfigurationProperties.asyncRecordedMessageMaxEntries(int maxEntries)System Property:
-Dmockserver.asyncRecordedMessageMaxEntries=...Environment Variable:
MOCKSERVER_ASYNC_RECORDED_MESSAGE_MAX_ENTRIES=...Property File:
mockserver.asyncRecordedMessageMaxEntries=...Example:
-Dmockserver.asyncRecordedMessageMaxEntries="5000"