Configuration

# mockserver.properties — local dev
mockserver.devMode=true
mockserver.logLevel=DEBUG
mockserver.enableCORSForAPI=true
mockserver.enableCORSForAllResponses=true

docker run -d --rm -p 1080:1080 \
  -e MOCKSERVER_DEV_MODE=true \
  -e MOCKSERVER_LOG_LEVEL=DEBUG \
  -e MOCKSERVER_ENABLE_CORS_FOR_API=true \
  -e MOCKSERVER_ENABLE_CORS_FOR_ALL_RESPONSES=true \
  mockserver/mockserver

# mockserver.properties — CI
mockserver.logLevel=WARN
mockserver.maxExpectations=1024
mockserver.maxLogEntries=4096
mockserver.initializationJsonPath=/ci/expectations.json

# mockserver.properties — production
mockserver.logLevel=INFO
mockserver.maxExpectations=16384
mockserver.maxLogEntries=65536
mockserver.metricsEnabled=true
mockserver.enableCORSForAPI=false
mockserver.enableCORSForAllResponses=false

-Dmockserver.propertyFile=/config/mockserver.properties

###############################
# 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
# maximum number of dynamically-discovered SANs the auto-generated certificate will accumulate (default 100)
mockserver.maxSubjectAlternativeNames=100
# number of days the auto-generated leaf certificate is valid for (default 397)
mockserver.sslCertificateLeafValidityInDays=397

# CORS (both default to false; set to true to enable)

# enable CORS for MockServer REST API
mockserver.enableCORSForAPI=true
# enable CORS for all responses
mockserver.enableCORSForAllResponses=true

-Dmockserver.propertyFile=/config/mockserver.json

{
  "logLevel": "INFO",
  "maxSocketTimeout": 120000,
  "dynamicallyCreateCertificateAuthorityCertificate": true,
  "directoryToSaveDynamicSSLCertificate": ".",
  "sslCertificateDomainName": "localhost",
  "sslSubjectAlternativeNameDomains": ["www.example.com", "www.another.com"],
  "sslSubjectAlternativeNameIps": ["127.0.0.1"],
  "maxSubjectAlternativeNames": 100,
  "sslCertificateLeafValidityInDays": 397,
  "enableCORSForAPI": true,
  "enableCORSForAllResponses": true
}

unrecognised MockServer configuration environment variable [MOCKSERVER_METRICS_ENABLE] - it is not a known configuration property and will be ignored (did you mean MOCKSERVER_METRICS_ENABLED?)

The the minimum level of logs to record in the event log and to output to system out (if system out log output is not disabled). The lower the log level the more log entries will be captured, particularly at TRACE level logging.

Type: string Default: INFO

Allowed values: TRACE, DEBUG, INFO, WARN, ERROR, OFF (also accepts java.util.logging equivalents: FINEST, FINE, WARNING, SEVERE)

Java Code:

ConfigurationProperties.logLevel(String level)

System Property:

-Dmockserver.logLevel=...

Environment Variable:

MOCKSERVER_LOG_LEVEL=...

Property File:

mockserver.logLevel=...

Example:

-Dmockserver.logLevel="DEBUG"

Removes the java.util.logging stdout console handler that MockServer installs by default, so MockServer's log lines are no longer printed to the console. It has no effect if you route logging through a different SLF4J binding or your own java.util.logging.config.file, and start-up failures are still printed to stderr. Log entries are still recorded in the in-memory event log exactly as before — verify, retrieveLogMessages and the dashboard's log view are unaffected, and no memory is saved. Use this to quiet a noisy console, for example in CI or when running many tests.

Type: boolean Default: false

Java Code:

ConfigurationProperties.disableSystemOut(boolean disableSystemOut)

System Property:

-Dmockserver.disableSystemOut=...

Environment Variable:

MOCKSERVER_DISABLE_SYSTEM_OUT=...

Property File:

mockserver.disableSystemOut=...

Example:

-Dmockserver.disableSystemOut="true"

Suppresses log output on every logging backend (the console, and any other appender your SLF4J provider sends to). Like disableSystemOut, this only stops log entries being printed — received-request/response entries are still recorded in the in-memory event log exactly as before, so verify, retrieveLogMessages and the dashboard's log view keep working, and no memory is saved. Use this to quiet all logging output, not to free heap — for that, lower maxLogEntries / maxEventLogSizeInBytes or raise the log level instead.

Type: boolean Default: false

Java Code:

ConfigurationProperties.disableLogging(boolean disableLogging)

System Property:

-Dmockserver.disableLogging=...

Environment Variable:

MOCKSERVER_DISABLE_LOGGING=...

Property File:

mockserver.disableLogging=...

Example:

-Dmockserver.disableLogging="true"

When enabled, log messages written to stdout/SLF4J use a compact single-line format showing summary information (method, path, status code, expectation ID) instead of full JSON-serialized request and response details. This significantly reduces log noise, especially in CI/CD environments or when running many tests.

The dashboard UI, verification, and log retrieval APIs are not affected — they continue to show full details.

Type: boolean Default: false

Java Code:

ConfigurationProperties.compactLogFormat(boolean enable)

System Property:

-Dmockserver.compactLogFormat=...

Environment Variable:

MOCKSERVER_COMPACT_LOG_FORMAT=...

Property File:

mockserver.compactLogFormat=...

Example output comparison:

Verbose (default):

INFO - 50850 returning response:

  {
    "statusCode" : 200,
    "body" : "{\"accessToken\":{...}}"
  }

 for request:

  {
    "method" : "POST",
    "path" : "/oauth2/token",
    "headers" : { ... }
  }

 from expectation:

  a735b798-8aec-4c15-b264-c6d3c93fda1d

Compact:

INFO - 50850 returning response: 200 for request: POST /oauth2/token from expectation: a735b798-8aec-4c15-b264-c6d3c93fda1d

Example:

-Dmockserver.compactLogFormat="true"

Tip: combine with logLevelOverrides for maximum control. For example, enable compact format and suppress startup/shutdown noise:

-Dmockserver.compactLogFormat="true" -Dmockserver.logLevelOverrides='{"SERVER":"WARN"}'

Override the log level for specific categories of log events or individual log message types. This allows fine-grained control over log verbosity without changing the global log level.

Keys can be category group names or individual log message type names. When both are specified, the individual type override takes precedence over the category group override, which takes precedence over the global logLevel.

This setting affects stdout/SLF4J output and the dashboard UI. The internal event log (used for verification) is not affected.

Note: Overrides can only suppress log events that are already captured at the global logLevel. For example, with logLevel=WARN, setting {"EXPECTATION_MATCHED":"INFO"} will not cause INFO-level match events to appear, because they are not generated when the global level is WARN. To see more verbose events for a specific category, first set the global logLevel low enough (e.g., INFO or DEBUG), then use overrides to suppress the noisy categories.

Type: map (JSON object) Default: {} (empty, global logLevel applies to all categories)

Category Groups:

MATCHING	EXPECTATION_MATCHED, EXPECTATION_NOT_MATCHED, NO_MATCH_RESPONSE
REQUEST_LIFECYCLE	RECEIVED_REQUEST, FORWARDED_REQUEST, EXPECTATION_RESPONSE, TEMPLATE_GENERATED
EXPECTATION_MANAGEMENT	CREATED_EXPECTATION, UPDATED_EXPECTATION, REMOVED_EXPECTATION, CLEARED
VERIFICATION	VERIFICATION, VERIFICATION_FAILED, VERIFICATION_PASSED, RETRIEVED
SERVER	SERVER_CONFIGURATION, AUTHENTICATION_FAILED, OPENAPI_RESPONSE_VALIDATION_FAILED
GENERAL	TRACE, DEBUG, INFO, WARN, ERROR, EXCEPTION

Java Code:

ConfigurationProperties.logLevelOverrides(Map<String, String> overrides)

System Property:

-Dmockserver.logLevelOverrides=...

Environment Variable:

MOCKSERVER_LOG_LEVEL_OVERRIDES=...

Property File:

mockserver.logLevelOverrides=...

REST API:

PUT /mockserver/configuration {"logLevelOverrides": {"MATCHING": "WARN", "EXPECTATION_MATCHED": "INFO"}}

Example - suppress per-expectation match failure noise while keeping match successes:

-Dmockserver.logLevelOverrides='{"MATCHING":"WARN","EXPECTATION_MATCHED":"INFO"}'

Example - suppress all matching and expectation management logs:

MOCKSERVER_LOG_LEVEL_OVERRIDES='{"MATCHING":"WARN","EXPECTATION_MANAGEMENT":"WARN"}'

If true (the default) the log event recording that a request matcher did not match will include a detailed reason why each non matching field did not match. See Troubleshooting Matching for how to use this when debugging.

Type: boolean Default: true

Java Code:

ConfigurationProperties.detailedMatchFailures(boolean enable)

System Property:

-Dmockserver.detailedMatchFailures=...

Environment Variable:

MOCKSERVER_DETAILED_MATCH_FAILURES=...

Property File:

mockserver.detailedMatchFailures=...

Example:

-Dmockserver.detailedMatchFailures="false"

At INFO, a request writes one "request didn't match expectation" log event for every expectation it was compared with, up to this limit. With many expectations stored and no limit, a flood of requests that match nothing spends most of its time writing those events: with 1,000 expectations each unmatched request writes 1,000 of them, and they quickly push older entries, such as the received requests that verification reads, out of the event log. The default of 50 keeps a request that matches nothing cheap and its log short.

This sets the most "didn't match" events written per request, in the order MockServer checks expectations (once 64 or more expectations are stored, those that can match the request's method and path come first). There is usually one event per expectation; an OpenAPI expectation writes one per operation. Every expectation is still compared, so which expectation matches, the closest-match event and the closest-match hint header do not change. For a request that matches nothing, the closest-match event ends with how many events were left out, for example 990 further did-not-match entries were not logged (maxLoggedMatchFailures). 50 is the default. -1 (or any negative value) writes all of them, which was the default before MockServer 9.0.0: set it if your tests or tools count these events or expect one for every expectation. 0 writes none.

Explain, Debug Mismatch and Explain Unmatched work out their answers again when asked, so they are not affected. The dashboard log shows only the events that were written.

Type: int Default: 50

Java Code:

ConfigurationProperties.maxLoggedMatchFailures(int maxLoggedMatchFailures)

System Property:

-Dmockserver.maxLoggedMatchFailures=...

Environment Variable:

MOCKSERVER_MAX_LOGGED_MATCH_FAILURES=...

Property File:

mockserver.maxLoggedMatchFailures=...

Example:

-Dmockserver.maxLoggedMatchFailures="-1"

If true (the default) verification failure messages will include a detailed diff showing how each recorded request differed from the expected request. This makes it easier to identify why a verification failed by highlighting per-field mismatches between the expected and actual requests.

For a request verification it also adds a verification summary: block at the end of the message: how many times the request was expected and how many times it matched, the three recorded requests that came closest without matching (with every field that differed), and how many requests arrived after the verification started. That last figure tells you whether a waiting verification (one with a timeout) saw any traffic at all. A response verification gets the same block for its responses, and a verification sequence's block says which step failed and which recorded requests came closest to it. The block is always added after the existing text, so code that reads the start of the message keeps working.

Disable this if verification failure messages are too verbose or if you prefer concise failure output.

Type: boolean Default: true

Java Code:

ConfigurationProperties.detailedVerificationFailures(boolean enable)

System Property:

-Dmockserver.detailedVerificationFailures=...

Environment Variable:

MOCKSERVER_DETAILED_VERIFICATION_FAILURES=...

Property File:

mockserver.detailedVerificationFailures=...

Example:

-Dmockserver.detailedVerificationFailures="false"

The event log holds at most maxLogEntries entries (and at most maxEventLogSizeInBytes of bodies). Once it is full, the oldest entries are discarded to make room for new ones. On a very busy server, log events can also be dropped before they are recorded at all. Either way those entries are gone — they can no longer be retrieved or verified.

This matters for verifications that assert something did not happen. If you call verify(request, never()) and the matching entries have been discarded, MockServer cannot tell the difference between "this request was never made" and "this request was made, but the record of it was thrown away". Previously it reported success, so a test asserting an endpoint was never called could quietly turn green simply because the log had filled up.

If true (the default) a verification that asserts an upper bound will fail, rather than pass, when the event log has discarded entries. The failure message lists what was lost since the event log was last reset, how many entries, and the fix for each cause. The dashboard shows the same on the verification's VERIFICATION_FAILED log entry.

Verification	Affected?	Why
never()	Yes	Asserts at most 0 calls
atMost(n)	Yes	Asserts at most n calls
exactly(n)	Yes	Asserts at most n calls
once()	Yes	Asserts exactly one call, so a discarded second call would go unnoticed
between(a, b)	Yes	Asserts at most b calls
atLeast(n)	No	No upper bound to violate
verify(request) (no times)	No	Defaults to atLeast(1)

once() is worth calling out: it is a very common way to verify a request, and although it reads like "this happened", it actually asserts "this happened exactly once" — an upper bound. Discarding entries can only ever make the observed count too low, never too high, which is why lower-bound verifications are safe and upper-bound ones are not.

If a verification starts failing for this reason, the message names one or more of these causes. Only the causes that happened since the last reset are listed:

The message says	What happened	Fix
log events were DROPPED … because the ring buffer was full	Log events arrived faster than the single logging thread could record them	Set the log level to WARN or ERROR, which stops non-matching expectations logging at all, or keep the log level and set maxLoggedMatchFailures (for example to 10) to log fewer of them per request. A larger ringBufferSize only absorbs short bursts.
log events were DROPPED … exceeded the in-flight byte budget	The request and response bodies waiting to be logged went over their memory limit	Set the log level to WARN or ERROR, or, if you have heap to spare, raise maxEventLogSizeInBytes above the budget quoted in the message. maxLoggedBodyBytes does not help here.
recorded entries were EVICTED … maximum number of entries	The log reached maxLogEntries and discarded its oldest entries	Increase maxLogEntries, or set the log level to WARN or ERROR — each request can log one entry, at INFO, for each expectation that does not match (at most 50 by default), plus two. To keep the log level, set maxLoggedMatchFailures lower to log fewer of those entries per request.
recorded entries were EVICTED … maximum size in bytes	The log reached maxEventLogSizeInBytes and discarded its oldest entries	Increase maxEventLogSizeInBytes, or set maxLoggedBodyBytes so each recorded entry is smaller.

Whatever the cause, clearing everything or resetting the event log between tests also clears this state, so each test starts with a complete log. Clearing only the entries that match a request does not.

Set to false to restore the previous behaviour, where these verifications could pass against an incomplete log.

Type: boolean Default: true

Java Code:

ConfigurationProperties.failVerificationOnEvictedLog(boolean enable)

System Property:

-Dmockserver.failVerificationOnEvictedLog=...

Environment Variable:

MOCKSERVER_FAIL_VERIFICATION_ON_EVICTED_LOG=...

Property File:

mockserver.failVerificationOnEvictedLog=...

Example:

-Dmockserver.failVerificationOnEvictedLog="false"

If true (default false) the ClientAndServer constructor or static factory methods will open the UI in the default browser when the log level is set to DEBUG.

Type: boolean Default: false

Java Code:

ConfigurationProperties.launchUIForLogLevelDebug(boolean enable)

System Property:

-Dmockserver.launchUIForLogLevelDebug=...

Environment Variable:

MOCKSERVER_LAUNCH_UI_FOR_LOG_LEVEL_DEBUG=...

Property File:

mockserver.launchUIForLogLevelDebug=...

Example:

-Dmockserver.launchUIForLogLevelDebug="false"

Enable the recording of metrics for different activities within MockServer, these are exposed via /mockserver/metrics in prometheus format

Type: boolean Default: false

Java Code:

ConfigurationProperties.metricsEnabled(boolean enable)

System Property:

-Dmockserver.metricsEnabled=...

Environment Variable:

MOCKSERVER_METRICS_ENABLED=...

Property File:

mockserver.metricsEnabled=...

Example:

-Dmockserver.metricsEnabled="true"

Threshold in milliseconds for flagging slow forwarded requests. When a forwarded request's total round-trip time exceeds this value, MockServer emits a WARN-level log entry and increments the mock_server_slow_requests_total Prometheus counter (when metrics are enabled). This is useful for detecting intermittently slow upstream services without scanning every recorded request manually.

Set to 0 to disable slow-request detection. See Network Latency Debugging for usage examples.

Type: long Default: 0 (disabled)

Java Code:

ConfigurationProperties.slowRequestThresholdMillis(long milliseconds)

System Property:

-Dmockserver.slowRequestThresholdMillis=...

Environment Variable:

MOCKSERVER_SLOW_REQUEST_THRESHOLD_MILLIS=...

Property File:

mockserver.slowRequestThresholdMillis=...

Example:

-Dmockserver.slowRequestThresholdMillis="500"

When enabled, MockServer registers an additional Prometheus histogram mock_server_request_duration_by_method_seconds with a method label for the HTTP method (GET, POST, PUT, etc.). This lets you compute per-method latency percentiles in your monitoring system. Cardinality is bounded to the set of standard HTTP methods.

Requires metricsEnabled to be true. See Network Latency Debugging for Prometheus query examples.

Type: boolean Default: false

Java Code:

ConfigurationProperties.metricsRequestDurationRouteLabels(boolean enable)

System Property:

-Dmockserver.metricsRequestDurationRouteLabels=...

Environment Variable:

MOCKSERVER_METRICS_REQUEST_DURATION_ROUTE_LABELS=...

Property File:

mockserver.metricsRequestDurationRouteLabels=...

Example:

-Dmockserver.metricsRequestDurationRouteLabels="true"

Register a custom callback that receives every log event generated by MockServer. This is useful for integrating MockServer logging with external systems (e.g. forwarding events to a monitoring tool, custom test reporting, or capturing specific events programmatically during tests).

This feature is programmatic only — there is no system property or environment variable equivalent because the listener is a Java callback.

Java Code:

Configuration.logEventListener(Consumer<LogEntry> listener)

ClientAndServer.setLogEventListener(Consumer<LogEntry> listener)

Example:

ClientAndServer mockServer = ClientAndServer.startClientAndServer(1080);
mockServer.setLogEventListener(logEntry -> {
    System.out.println("Event: " + logEntry.getType() + " - " + logEntry.getTimestamp());
});

When enabled, applies a developer-friendly configuration profile that reduces memory usage for laptop and test-suite workloads. The following defaults are overridden (only for properties the user has not explicitly set via system property, environment variable, or properties file):

• maxLogEntries is set to 1,000 (instead of the heap-based default up to 250,000)
• maxExpectations is set to 1,000 (instead of the heap-based default up to 15,000)

This is useful when running MockServer locally during development, where retaining tens of thousands of log entries is unnecessary and wastes memory.

Enabled by default under the JUnit integrations. The JUnit 4 rule (MockServerRule) and the JUnit 5 extension (MockServerExtension) turn dev mode on by default, because a test suite that starts many short-lived MockServer instances in one JVM benefits most from the smaller, deterministic footprint (a measured ~117 MB down to ~52 MB across 32 in-JVM instances). The practical consequence is the 1,000-entry log cap: if a single test records more than 1,000 log entries against one MockServer instance, the oldest are overwritten, so a verify that reaches back past the most recent 1,000 entries can stop matching. When dev mode is in effect MockServer logs a one-time INFO line naming the effective sizes and how to change them. To keep the old behaviour under JUnit, either raise the caps explicitly (-Dmockserver.maxLogEntries=… / -Dmockserver.maxExpectations=…, which win over the dev-mode default) or turn dev mode off with -Dmockserver.devMode=false (or MOCKSERVER_DEV_MODE=false). An explicit setting always beats the default. The Spring test integration and a directly-constructed ClientAndServer do not turn dev mode on themselves — for those it stays off unless you enable it. One caveat if you mix them in the same JVM: enabling dev mode is global, so once a JUnit rule or extension has run in a test fork, a ClientAndServer constructed directly afterwards in that same fork inherits the dev-mode store sizes too (unless it sets its own).

Type: boolean Default: false (server default; the JUnit 4 rule and JUnit 5 extension default it to true)

Java Code:

ConfigurationProperties.devMode(boolean enable)

System Property:

-Dmockserver.devMode=...

Environment Variable:

MOCKSERVER_DEV_MODE=...

Property File:

mockserver.devMode=...

Command Line:

mockserver run -p 1080 --dev

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 (JVM heap size in KB / 10) and 15000

The default is calculated automatically from the JVM heap size (the -Xmx maximum), so it is the same for every MockServer instance in a JVM and does not depend on how much memory happens to be in use when the first instance starts. 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. On JVMs that do not report a usable heap maximum (for example GraalVM native images), the default falls back to a floor of 1,000 — set the property explicitly to override.

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 total estimated size in bytes of the expectations held in memory before the oldest, lowest-priority ones are evicted to stay within the budget. This bounds memory when individual expectations are large (big request-matcher or response bodies), which maxExpectations cannot, since a count cap treats a 10 MB expectation the same as a 10-byte one. A JSON request matcher is the heaviest case: it is parsed into a retained node tree many times the size of the raw JSON.

Off (0) by default, so expectations are bounded only by maxExpectations unless you set this. It is opt-in because expectations are state you configured, not observational data — evicting one silently removes a mock you added. Turn it on if you register many large expectations and want a hard memory ceiling; a reasonable starting point is about an eighth of the JVM heap (leaving room for the request log, Netty buffers and the working set). When set, whichever of maxExpectations or this is reached first evicts, and the eviction is announced once per server in the log.

Type: long Default: 0 (disabled)

Java Code:

ConfigurationProperties.maxExpectationsSizeInBytes(long bytes)

System Property:

-Dmockserver.maxExpectationsSizeInBytes=...

Environment Variable:

MOCKSERVER_MAX_EXPECTATIONS_SIZE_IN_BYTES=...

Property File:

mockserver.maxExpectationsSizeInBytes=...

Example:

-Dmockserver.maxExpectationsSizeInBytes="33554432"

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 (JVM heap size in KB / 8) and 250000

The default is calculated automatically from the JVM heap size (the -Xmx maximum), so it is the same for every MockServer instance in a JVM and does not depend on how much memory happens to be in use when the first instance starts. 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 30,000 entries covers around 10,000-15,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. On JVMs that do not report a usable heap maximum (for example GraalVM native images), the default falls back to a floor of 1,000 — set the property explicitly to override. See troubleshooting performance for detailed guidance.

Independent of the ring buffer: maxLogEntries controls how much history is retained, not the size of the in-flight log event ring buffer. The ring buffer is a separate, smaller buffer sized by ringBufferSize (default min(maxLogEntries, 16,384)), so raising maxLogEntries for more retention no longer inflates the ring buffer's fixed memory. You can set maxLogEntries to any value — it does not need to be a power of 2.

Java Code:

ConfigurationProperties.maxLogEntries(int count)

System Property:

-Dmockserver.maxLogEntries=...

Environment Variable:

MOCKSERVER_MAX_LOG_ENTRIES=...

Property File:

mockserver.maxLogEntries=...

Example:

-Dmockserver.maxLogEntries="20000"

Number of slots in the in-memory log event ring buffer. This buffer holds log events briefly while they are passed from the threads handling requests to the single thread that writes them to the log — it is not the retained log history (that is controlled separately by maxLogEntries). The ring buffer only needs to absorb short bursts of log events, so it can be much smaller than the retained history.

Type: int Default: minimum of maxLogEntries and 16,384 (rounded up to the next power of 2)

Raising this absorbs a short burst of small log entries without dropping them — it gives the consumer thread more room to catch up once the burst ends. It does not help against sustained drops at a verbose log level, where entries arrive faster than one thread can ever drain them (see below); for that, lower the log level instead, or keep INFO and set maxLoggedMatchFailures. Lower ringBufferSize to save a little memory on a workload that retains a lot of history but receives requests slowly. The value is rounded up to the next power of 2 because the underlying LMAX Disruptor requires it.

At logLevel INFO, one thread renders every log entry, and on a busy server that thread is the more likely bottleneck, not this buffer's size. In our own load tests we estimate that thread falls behind and starts dropping entries from roughly 8,000–10,000 requests/second on a 6-core server with four expectations, where the request matches the last one (about six log entries per request). Each expectation checked before a match adds another entry, so with more expectations drops start at a lower rate — roughly half as many requests per second with ten (again matching the last one). Raising ringBufferSize delays this but does not remove it, because the entries still accumulate faster than one thread can render them. For a high-throughput workload that calls verify, prefer running at WARN or ERROR (see Log Level), which skips the per-expectation diagnostic entries that saturate this thread. To keep INFO, set maxLoggedMatchFailures (for example to 10) instead: it caps how many of those entries each request writes. A once-only WARN (“Log event ring buffer full — dropping log events…”) naming both remedies is logged the first time this happens after each reset regardless of metricsEnabled, unless logging or system-out is disabled. You can also watch for drops with metricsEnabled set to true — the mock_server_dropped_log_events counter, which counts these drops under the label reason="ring_full", and the dashboard's log-pressure banner, which says which kind of drop happened and what to change, both need it, and show nothing while it is off (the default).

Previously the ring buffer was sized from maxLogEntries, so a large retention setting (e.g. maxLogEntries=250000) forced a 262,144-slot ring (~29 MB of pre-allocated, mostly-empty slots). The default 16,384 ceiling caps that overhead while leaving small deployments unchanged.

Java Code:

ConfigurationProperties.ringBufferSize(int size)

System Property:

-Dmockserver.ringBufferSize=...

Environment Variable:

MOCKSERVER_RING_BUFFER_SIZE=...

Property File:

mockserver.ringBufferSize=...

Example:

-Dmockserver.ringBufferSize="8192"

OOM guard for the in-memory event log. Entry count (maxLogEntries) alone cannot protect a memory-constrained server, because a count cap treats a 10 MB body the same as a 10-byte one — so a few thousand large request/response bodies (e.g. LLM tool schemas, growing conversation context, or accumulated SSE chunks) can exhaust the heap even when the entry count is low. This byte budget is a second, independent bound on the same log: once the retained bodies exceed it, the oldest entries are evicted (oldest-first) until they fit. Whichever bound — count or bytes — is reached first evicts.

On by default, with a log-level-aware divisor. The default is derived from the JVM heap ceiling and is constant for the JVM's life. At INFO /WARN /ERROR /OFF the budget is a twentieth of the ceiling budget (the heap ceiling less 20 MiB); at DEBUG /TRACE it is a twelfth. On a 1 GiB heap (-Xmx1g) that is about 50 MiB counted at INFO and WARN and 84 MiB at DEBUG; on a 2 GiB heap, about 101 MiB and 169 MiB.

Why the INFO and WARN default is small, and what it costs you. The heap could safely hold about three times more (a seventh of the ceiling), but under heavy load entries kept that long outlive the garbage collector's short-lived memory area, get copied to long-lived memory, and keep the collector busy; on a 2-core, 1 GiB container (about 460 MiB heap) a seventh capped healthy throughput (the highest load with a median response time under 1 ms) at about 31,000 requests per second, while budgets either side of a twentieth kept it at about 36,000–38,000 by the same measure (the twentieth itself is interpolated from those runs). The trade-off is history: by default the log keeps about a third as many past requests as it would at a seventh wherever this budget is what limits the log (on large heaps with small bodies the entry-count limit maxLogEntries may bind first, so fewer are lost — at a 4 GB heap with small requests, about two-thirds are kept), so verify(), retrieve and the dashboard see fewer of them, and an upper-bound verification fails sooner once the oldest are evicted. At INFO the default was a twelfth until this release; a twentieth keeps about 40% fewer past requests than that, in exchange for less of the same garbage-collector work and a lower worst-case response time when the server is close to the most traffic it can log (measured on 2-core containers with 1 GiB and 2 GiB). If you need more history and are not running near your throughput limit, set maxEventLogSizeInBytes higher, for example to a twelfth or a seventh of your heap.

Entries still waiting to be logged have their own cap. When the server receives more traffic than it can log, a backlog of entries waits to be recorded. That backlog is capped at the larger of maxEventLogSizeInBytes and a seventh of the ceiling (a twelfth at DEBUG /TRACE), so a small budget does not cause log events to be dropped during a burst. Setting maxEventLogSizeInBytes above that cap raises the backlog cap with it; setting it to 0 removes both. The defaults are chosen so that the real heap the whole log holds, kept entries and backlog together, stays at or below about a quarter of the ceiling at either log level even under overload, leaving room for expectations, network buffers and the rest of the server.

Why the two levels differ. The budget counts an estimate of each entry's size, and the heap actually holds a multiple of that estimate which depends on your traffic. Measured on live heaps in September 2026 under both the G1 and ZGC garbage collectors, the log's kept entries held 0.50–0.97× their counted size at WARN and 1.04–2.31× at INFO, and the entries waiting to be logged held up to another 0.72× of theirs. The highest figures came from a server sent more traffic than it could log. The difference is that at INFO /DEBUG /TRACE MockServer writes every entry to system-out and keeps the formatted message (which embeds the body as text) on the entry for its whole life; once the log has caught up, forwarded proxy traffic is the most expensive case, because its message includes the request, the response and a curl command. Entries still waiting are not rendered yet, so this does not make the backlog itself heavier. An entry that quotes a request or response no longer keeps its formatted message, and re-measured in October 2026 the kept entries held 0.70–1.00× their counted size at INFO on JSON and proxy traffic, so the backlog cap at INFO is now the same seventh of the ceiling as at WARN, and the whole log still stays under about a fifth of the heap on that traffic. DEBUG and TRACE were not re-measured and keep a twelfth. The kept-history budget at INFO is now the same twentieth as at WARN; it used to be a twelfth.

This default is new in this release. Previously maxEventLogSizeInBytes was off unless you set it, so the log was bounded by entry count alone — which cannot protect a memory-constrained server, because a count cap treats a 10 MB body the same as a 10-byte one. If you are upgrading, you are gaining a bound that did not exist before; with large bodies the log may now keep fewer entries than it used to, and it evicts the oldest rather than running out of memory. The divisors were set from live-heap and throughput measurement: the backlog cap (a seventh of the ceiling, a twelfth at DEBUG /TRACE) keeps the worst measured whole log, kept entries plus the waiting backlog, at or below about a quarter of the heap ceiling, and the smaller twentieth at INFO and WARN keeps kept entries from slowing the garbage collector under load. Changing the log level changes both bounds together. If you share the heap with other large workloads and want a tighter bound, set maxEventLogSizeInBytes explicitly — note that a value below the default limits only the kept entries, not the backlog waiting to be logged; to limit that too, lower ringBufferSize or the heap (-Xmx); raise it if you want more retained history and have the heap headroom, or set it to 0 to bound the log by entry count only.

The budget counts each entry's body bytes, header bytes and a fixed per-entry structural overhead (via LogEntry.estimatedHeapSize()). It deliberately does not count the rendered log message — that is why DEBUG and TRACE keep a tighter backlog cap; an entry that quotes a request or response no longer keeps its message, which is why INFO now has the same backlog cap as WARN. The message is materialised after an entry's weight is fixed, and counting it would break the invariant that an entry weighs the same when evicted as when added.

Eviction is not silent. The first time the log evicts, MockServer logs a single WARN naming which bound was hit (count or bytes), its current value, and how to keep more coverage (for the entry-count limit, that includes lowering the log level or setting maxLoggedMatchFailures to keep INFO); and with the default failVerificationOnEvictedLog=true an upper-bound verification (never(), atMost(n), exactly(n), once(), between(a,b)) fails rather than silently passing on discarded evidence. Only these size-based bounds evict; the received-request and response entries a verification reads are recorded regardless of log level.

See Proxying LLM / Large-Body Traffic Without OOM for the recommended combo with disk capture.

Type: long Default: heap-based — a twentieth of the ceiling budget at INFO/WARN/ERROR/OFF, a twelfth at DEBUG/TRACE; 0 disables the byte budget

Java Code:

ConfigurationProperties.maxEventLogSizeInBytes(long bytes)

Configuration.maxEventLogSizeInBytes(Long bytes)

System Property:

-Dmockserver.maxEventLogSizeInBytes=...

Environment Variable:

MOCKSERVER_MAX_EVENT_LOG_SIZE_IN_BYTES=...

Property File:

mockserver.maxEventLogSizeInBytes=...

Example:

-Dmockserver.maxEventLogSizeInBytes="268435456"

Secondary memory valve. When set to a value > 0, request and response bodies kept in memory in the event log are truncated beyond this many bytes. A x-mockserver-body-truncated: <originalLength> header is added to the in-memory copy so a reader can tell the body was clipped and how large it originally was. Log messages, on the console and in logs retrieved as text, quote the truncated copy too, and show its body as base64, because a truncated body is kept as bytes. The bodies of an expectation a log entry names or quotes (for example the closest match to a request that matched nothing, or a removed expectation) are truncated the same way, and so is a long explanation of why a request did not match, which ends with how many characters were left out; the expectations themselves are not changed.

This is symmetric with the existing maxStreamingCaptureBytes cap (default 256 KB) applied to SSE streams.

It also limits how much of each binary (non-HTTP) message MockServer proxies or mocks is shown in the log: each log entry shows the hex of the message's first bytes up to this limit, followed by the message's full length, for example ...(70000 bytes, only the first 4096 logged, maxLoggedBodyBytes). A binaryProxyListener still receives every byte.

Important: if disk capture (persistRecordedRequestsToDisk) is also enabled, the disk archive always records the full body — the disk write happens before truncation. For full-fidelity off-line processing, leave this at 0 and rely on the byte-budget eviction (maxEventLogSizeInBytes) to bound the in-memory window instead.

Verification impact: setting this to a positive value breaks verification against request or response body content — a verify that matches on body returns 406 against a truncated entry where the untruncated entry returns 202. Verification by path, method, and header is not affected. The truncation is visible rather than silent: the clipped copy carries a x-mockserver-body-truncated: <originalLength> header in the event log and dashboard.

When 0 (the default), bodies are kept in full in the event log (no truncation).

Type: int Default: 0 (unlimited)

Java Code:

ConfigurationProperties.maxLoggedBodyBytes(int bytes)

Configuration.maxLoggedBodyBytes(Integer bytes)

System Property:

-Dmockserver.maxLoggedBodyBytes=...

Environment Variable:

MOCKSERVER_MAX_LOGGED_BODY_BYTES=...

Property File:

mockserver.maxLoggedBodyBytes=...

Example:

-Dmockserver.maxLoggedBodyBytes="262144"

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"

Maximum number of WebSocket frames recorded per proxied (passthrough) WebSocket connection. When MockServer proxies a WebSocket upgrade to a real upstream server (no matching WebSocket expectation), the relayed frames (text, binary, ping, pong, close) are captured into a per-connection transcript that is written to the request log when the connection closes, so retrieveRecordedRequests and the dashboard show the WebSocket traffic. Once this limit is reached the remaining frames on that connection are still relayed but not recorded, which bounds memory on long-lived connections.

Type: int Default: 1000 (set to 0 to disable frame recording; the upgrade handshake is still recorded)

Java Code:

ConfigurationProperties.webSocketProxyMaxRecordedFrames(int count)

System Property:

-Dmockserver.webSocketProxyMaxRecordedFrames=...

Environment Variable:

MOCKSERVER_WEB_SOCKET_PROXY_MAX_RECORDED_FRAMES=...

Property File:

mockserver.webSocketProxyMaxRecordedFrames=...

Example:

-Dmockserver.webSocketProxyMaxRecordedFrames="500"

Idle timeout, in seconds, for a proxied (passthrough) WebSocket connection. When set to a positive value, a relayed WebSocket connection whose two directions have both been idle (no message sent either way) for this many seconds is closed, reaping half-open or abandoned relays.

The default is 0, which disables idle reaping — long-lived WebSocket connections that are legitimately idle (for example waiting for server-pushed events) are left open and rely on TCP keep-alive. Raise it only if you need MockServer to bound how long an idle passthrough relay is held open.

Type: int Default: 0 (disabled)

Java Code:

ConfigurationProperties.webSocketProxyIdleTimeoutSeconds(int seconds)

System Property:

-Dmockserver.webSocketProxyIdleTimeoutSeconds=...

Environment Variable:

MOCKSERVER_WEB_SOCKET_PROXY_IDLE_TIMEOUT_SECONDS=...

Property File:

mockserver.webSocketProxyIdleTimeoutSeconds=...

Example:

-Dmockserver.webSocketProxyIdleTimeoutSeconds="300"

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

This setting is startup-only: set it before MockServer starts (system property, environment variable, property file or Configuration). A PUT /mockserver/configuration request cannot change it (a different value is ignored and a warning is logged), so a caller of the control plane cannot redirect where MockServer writes files.

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="."

docker run -d --rm -p 1080:1080 \
  --env MOCKSERVER_MAX_EXPECTATIONS=1000 \
  --env MOCKSERVER_MAX_LOG_ENTRIES=5000 \
  mockserver/mockserver

Introduces a delay (in milliseconds) before protocol detection on new TCP connections. This can be used to simulate slow connection establishment, such as when testing client timeout handling or connection pooling behaviour under latency.

Type: long Default: 0

Java Code:

ConfigurationProperties.connectionDelayMillis(long millis)

Configuration.connectionDelay(Delay delay)

System Property:

-Dmockserver.connectionDelayMillis=...

Environment Variable:

MOCKSERVER_CONNECTION_DELAY_MILLIS=...

Property File:

mockserver.connectionDelayMillis=...

Example:

-Dmockserver.connectionDelayMillis="500"

docker run -d --rm -p 1080:1080 \
  -e MOCKSERVER_MAX_LOG_ENTRIES=5000 \
  mockserver/mockserver

docker run -d --rm -p 1080:1080 \
  -e JAVA_TOOL_OPTIONS="-XX:+UseZGC -Xmx1g" \
  -e MOCKSERVER_MAX_LOG_ENTRIES=1000 \
  -e MOCKSERVER_MAX_EXPECTATIONS=100 \
  mockserver/mockserver

docker run -d --rm -p 1080:1080 \
  -e JAVA_TOOL_OPTIONS="-XX:+UseZGC -Xmx512m" \
  -e MOCKSERVER_MAX_LOG_ENTRIES=100 \
  -e MOCKSERVER_LOG_LEVEL=WARN \
  mockserver/mockserver

docker inspect --format '{{json .State}}' <container>
# "OOMKilled": true, "ExitCode": 137

docker run -d --rm -p 1080:1080 \
  -e JAVA_TOOL_OPTIONS="-XX:+UseZGC -Xmx512m" \
  mockserver/mockserver

services:
  mockServer:
    image: mockserver/mockserver
    ports:
      - "1080:1080"
    environment:
      JAVA_TOOL_OPTIONS: "-XX:+UseZGC -Xmx512m"
      MOCKSERVER_MAX_LOG_ENTRIES: "5000"

java -Xmx512m -jar mockserver-netty.jar -serverPort 1080

docker run -d --rm -p 1080:1080 \
  -e MOCKSERVER_OUTPUT_MEMORY_USAGE_CSV=true \
  -e MOCKSERVER_MEMORY_USAGE_CSV_DIRECTORY=/config \
  -v $(pwd):/config \
  mockserver/mockserver

java -Xmx2g \
  -Dmockserver.maxLogEntries=5000 \
  -Dmockserver.maxEventLogSizeInBytes=268435456 \
  -Dmockserver.persistRecordedRequestsToDisk=true \
  -Dmockserver.persistedRecordedRequestsPath=recordedRequests.ndjson \
  -jar mockserver-netty.jar -serverPort 1080

./mockserver-ui/scripts/launch-with-llm-capture.sh opencode

When enabled (the default), MockServer uses the native Linux epoll transport for higher throughput and lower latency. This is also required for transparent-proxy SO_ORIGINAL_DST resolution, which needs epoll socket channels to read the original destination address from iptables REDIRECT rules. The official Docker images cannot yet use that lookup even on epoll, so there it falls back to the Linux connection-tracking table.

It also applies to the HTTP/3 port (http3Port): with epoll, MockServer reads and sends UDP packets in batches, which keeps large HTTP/3 downloads from stalling on a Linux host with a small UDP receive buffer. See HTTP/3.

On non-Linux platforms (macOS, Windows) this setting has no effect — MockServer transparently falls back to the Java NIO transport regardless. Set to false to force the NIO transport on all platforms, including Linux.

At start-up MockServer logs which transport it chose, for example using native epoll transport or using NIO transport (native epoll transport unavailable: ...). Check this line if you rely on epoll. Docker images published before this release ran NIO even on Linux, because their bundled epoll library could not be loaded.

This property is read at start-up only.

Type: boolean Default: true

Java Code:

ConfigurationProperties.useNativeTransport(boolean enable)

System Property:

-Dmockserver.useNativeTransport=...

Environment Variable:

MOCKSERVER_USE_NATIVE_TRANSPORT=...

Property File:

mockserver.useNativeTransport=...

Example:

-Dmockserver.useNativeTransport=true

How many connections the kernel may hold after completing their TCP handshake, while they wait for MockServer to accept them.

This matters when many clients connect at once — a load test ramping up, a connection pool refilling, or a fleet of containers starting together. Steady traffic over existing keep-alive connections does not touch the accept queue at all.

What a full queue looks like. The kernel does not refuse the connection — it silently drops the handshake packet, and the client retransmits after its initial timeout, typically one second on Linux. So the symptom is a median latency that jumps to around a second with no errors at all, which reads like a slow server rather than a connection limit. If you see that shape, raise this before looking anywhere else.

The OS caps this value. Your setting is reduced to the operating system's limit, so raise both together:

• Linux: sysctl -w net.core.somaxconn=16384 (commonly 4096 by default)
• Docker: docker run --sysctl net.core.somaxconn=16384 ... — containers get their own value, so setting it on the host is not enough
• macOS: sysctl -w kern.ipc.somaxconn=16384

Type: int Default: 1024

Raise this deliberately, not routinely. A deeper queue lets the kernel admit connections your server may then be unable to serve, so the default acts as backpressure: the failure mode changes from slow to dead. Raise it when you have measured that connections are being dropped at the queue, and raise somaxconn with it.

Java Code:

ConfigurationProperties.soBacklog(int backlog)

System Property:

-Dmockserver.soBacklog=...

Environment Variable:

MOCKSERVER_SO_BACKLOG=...

Property File:

mockserver.soBacklog=...

Example:

-Dmockserver.soBacklog=16384

How long, in milliseconds, a client connection may sit completely idle before MockServer closes it. Every open connection costs memory even when it carries no traffic (roughly 4 KB of kernel socket memory plus MockServer's own per-connection state), so clients that open keep-alive connections and never close them can slowly push a container towards its memory limit. This timeout releases them.

Only genuinely quiet connections are closed: nothing read or written for the whole timeout and nothing in progress. A connection is never closed by this timeout while it is:

• waiting for a response — a delayed response, a slow forward, or a request paused at a breakpoint
• streaming a response — Server-Sent Events, chunked or gRPC streaming, however long the gaps between messages
• carrying an open HTTP/2 stream
• a WebSocket or a raw (non-HTTP) proxied connection

A CONNECT or SOCKS proxy tunnel is treated like any other connection: it is closed, together with MockServer's own internal connection for it, once nothing has passed through it for the whole timeout and no request sent through it is waiting for its response. A tunnel with a request still being uploaded, a delayed or streamed response, or an open HTTP/2 stream is never closed by this timeout. Clients that pool proxy tunnels reconnect as they do for any idle connection closed by a server.

Exception: HTTP/1.1 requests pipelined behind a stuck response. With http1PipeliningInOrder on (the default), a request pipelined behind one MockServer is still answering is held, not counted as waiting for a response on its own account. If the response it is held behind makes no progress at all — no bytes written, no stream event — for this same timeout, MockServer closes the connection anyway, so a lost response does not hold pipelined requests open forever. Set the timeout to 0 and this exception stops closing connections too, but MockServer still logs one warning per connection after 5 minutes with no progress regardless of the timeout you set, so a stuck connection stays visible. A long deliberate delay (for example a breakpoint, or a response delayed longer than this timeout) with another request pipelined behind it is cut by this exception, and so is a streamed response whose gap between events is longer than this timeout, even though a stream on its own is never closed by this timeout (above); raise the timeout if you rely on delays or streaming gaps that long together with pipelining.

An error() action that keeps the connection open is not waiting for anything once it has sent its bytes, or if it sends none, so that connection counts as idle and is closed once the timeout passes. A CONNECT or SOCKS proxy tunnel that carried such a request is closed on the same terms.

The same goes for a response whose status code is 1xx (other than 101), such as 102 or 103: it is the whole of what the expectation sends, so nothing more is coming. Over HTTP/1.1 the connection stays open and is closed once the timeout passes. Over HTTP/2 MockServer sends the 1xx and then resets that request's stream (RST_STREAM with NO_ERROR), so the client's request fails at once instead of waiting for a final response, and the connection is closed once it has been idle for the timeout. Over HTTP/3 MockServer sends the 1xx (101 included, as HTTP/3 has no upgrade) without any body or trailers the expectation has, and then resets the stream with H3_NO_ERROR; the client may not see the 1xx before the reset. Over HTTP/2 and HTTP/3, MockServer logs one warning the first time each such expectation is used.

Mainstream HTTP clients (Java, OkHttp, Apache, Python, Node, Go) notice a server closing an idle pooled connection and open a new one, so the 5 minute default should go unnoticed by normal test suites. In rare cases a request sent at the exact moment a connection is closed may fail and need a retry, as with any server that closes idle keep-alive connections. Set it to 0 to never close idle connections, which was the behaviour before this setting existed. The value applies to connections accepted after it is changed.

Type: long Default: 300000 (5 minutes)

Java Code:

ConfigurationProperties.inboundConnectionIdleTimeoutMillis(long millis)

System Property:

-Dmockserver.inboundConnectionIdleTimeoutMillis=...

Environment Variable:

MOCKSERVER_INBOUND_CONNECTION_IDLE_TIMEOUT_MILLIS=...

Property File:

mockserver.inboundConnectionIdleTimeoutMillis=...

Example:

-Dmockserver.inboundConnectionIdleTimeoutMillis=60000

The most client connections MockServer will hold open at once. When the limit is reached, a new connection is closed immediately (the client sees a connection reset straight away rather than hanging), a warning is logged at most every 10 seconds, and mock_server_inbound_connections_rejected_total is incremented. As soon as a connection closes, new ones are accepted again.

Use it to put a hard ceiling on connection memory in a memory-limited container, for example when many load-test clients each hold a pool of keep-alive connections. Watch mock_server_inbound_connections_open to choose a value. Each CONNECT or SOCKS proxy tunnel uses two connections (the client's plus MockServer's own internal connection to itself); if the second is refused the client receives a 502.

HTTP/3 (QUIC) connections are not counted. MockServer's own start-up warm-up request (see startupWarmup) holds one connection for a few seconds after start, so allow for it with a very small limit. The value is read for each new connection, so it can be changed while MockServer is running.

Type: int Default: 0 (no limit)

Java Code:

ConfigurationProperties.maxInboundConnections(int maxConnections)

System Property:

-Dmockserver.maxInboundConnections=...

Environment Variable:

MOCKSERVER_MAX_INBOUND_CONNECTIONS=...

Property File:

mockserver.maxInboundConnections=...

Example:

-Dmockserver.maxInboundConnections=5000

How long, in milliseconds, a response may wait for a client that has stopped reading it before MockServer gives up on it. A client that stops reading (a hung test, a paused debugger, a consumer that stops taking a stream) would otherwise keep what is waiting for it for as long as its connection stays open: an aggregated response up to its full size, and for a streamed response up to maxResponseBodySize plus an open connection to the upstream it is forwarded from.

When bytes of a response have been waiting for the whole timeout and the client has taken none of them, the response ends incomplete, is logged as a warning and is counted by the mock_server_response_write_stalls_total metric:

• HTTP/1.1: the connection is closed (for a CONNECT or SOCKS tunnel, the tunnel is closed)
• HTTP/2 (including HTTP/2 inside a CONNECT or SOCKS tunnel) and HTTP/3: only that stream is reset; other streams on the connection carry on (an HTTP/2 client that stops reading the connection altogether has the connection closed). An HTTP/2 stream that was waiting only for flow-control window held by the stalled stream is not reset before it, and gets another timeout period to receive that window once the stalled stream is reset. An HTTP/2 client counts as reading a stream only while the stream's data is actually being sent to it: flow-control frames that let no data be sent (a WINDOW_UPDATE while the connection's window is used up, or a changed initial window size) do not keep a stalled stream open. An HTTP/3 stream that has been sent little or nothing because stalled streams hold the connection's flow-control credit also gets another timeout period once such a stream is reset
• a streamed (forwarded) response: its upstream connection is closed too

A client that keeps taking some of the response at least once per timeout period is not affected, and neither is a client waiting for a delayed or slow response, because nothing is waiting for it to read. The same applies to a WebSocket whose client stops reading the messages sent to it. The operating system sends data to a slow reader in bursts, sometimes seconds apart, so keep the timeout well above a few seconds; the 1 minute default leaves plenty of room. Set it to 0 to never cut off a stalled client, which was the behaviour before this setting existed. The value applies to connections accepted after it is changed.

Type: long Default: 60000 (1 minute)

Java Code:

ConfigurationProperties.responseWriteStallTimeoutMillis(long millis)

System Property:

-Dmockserver.responseWriteStallTimeoutMillis=...

Environment Variable:

MOCKSERVER_RESPONSE_WRITE_STALL_TIMEOUT_MILLIS=...

Property File:

mockserver.responseWriteStallTimeoutMillis=...

Example:

-Dmockserver.responseWriteStallTimeoutMillis=120000

Number of threads for main event loop

These threads are used for fast non-blocking activities such as:

• reading and de-serialise all requests
• serialising and writing control plane responses
• adding, updating or removing expectations
• verifying requests or request sequences
• retrieving logs

Expectation actions are handled in a separate thread pool to ensure slow object or class callbacks and response / forward delays do not impact the main event loop.

Type: int Default: 5

Java Code:

ConfigurationProperties.nioEventLoopThreadCount(int count)

System Property:

-Dmockserver.nioEventLoopThreadCount=...

Environment Variable:

MOCKSERVER_NIO_EVENT_LOOP_THREAD_COUNT=...

Property File:

mockserver.nioEventLoopThreadCount=...

Example:

-Dmockserver.nioEventLoopThreadCount="5"

Number of threads for the action handler thread pool

These threads are used for handling actions such as:

• serialising and writing expectation or proxied responses
• handling response delays in a non-blocking way (i.e. using a scheduler)
• executing class callbacks
• handling method / closure callbacks (using web sockets)

Type: int Default: maximum of 5 or available processors count

Java Code:

ConfigurationProperties.actionHandlerThreadCount(int count)

System Property:

-Dmockserver.actionHandlerThreadCount=...

Environment Variable:

MOCKSERVER_ACTION_HANDLER_THREAD_COUNT=...

Property File:

mockserver.actionHandlerThreadCount=...

Example:

-Dmockserver.actionHandlerThreadCount="5"

Maximum number of matched requests that can be waiting at the same time for a configured delay before their response is sent. This covers a response or forward delay, globalResponseDelayMillis and chaos latency.

Each waiting request is held in memory until its delay ends, so a high request rate against a slow expectation (for example 1,000 requests per second with a 10 second delay keeps 10,000 requests waiting) can use a lot of heap. When the limit is reached, further requests are answered straight away with 503 Service Unavailable and a Retry-After: 1 header instead of being held, so the server stays healthy.

A request answered this way has still matched its expectation: it counts towards the expectation's times (so a once() expectation is used up), may have used a rate-limit allowance, and has no response entry in the request log. A forwarded response that is waiting only for chaos latency is sent immediately without the latency instead of being refused, because the upstream has already been called.

Delayed side actions (after-actions, secondary actions and step side effects) have a separate allowance of the same size. When it is full further ones are skipped and logged, so they never cause a 503.

Delayed replies of a two-way (bidirectional) WebSocket mock have a third allowance of the same size, counted in reply messages. A reply to one incoming message is always sent completely or not at all: when the allowance is full, the WebSocket is closed with status 1013 (Try Again Later) and none of that reply is sent. Before that point, a single connection with more than 128 delayed replies still waiting simply stops being read until they drain, which slows a fast client down instead of failing it.

Rejections are reported in a WARN log line at most every 10 seconds and, when metrics are enabled (metricsEnabled), counted by the mock_server_overload_rejections metric (with reason delayed_responses, delay_skipped, side_actions or websocket_replies); the mock_server_pending_delayed_tasks metric shows how many are currently waiting.

Raise this if you deliberately run many slow requests at once and have the heap for them; set it to 0 to restore the previous unlimited behaviour (not recommended).

Type: int Default: maximum heap divided by 64 KB (an estimate of the memory each waiting request holds), up to 100,000 (about 8,000 for a 512 MB heap; 1,000 if the JVM reports no heap limit)

Java Code:

ConfigurationProperties.maxPendingDelayedResponses(int maxPendingDelayedResponses)

System Property:

-Dmockserver.maxPendingDelayedResponses=...

Environment Variable:

MOCKSERVER_MAX_PENDING_DELAYED_RESPONSES=...

Property File:

mockserver.maxPendingDelayedResponses=...

Example:

-Dmockserver.maxPendingDelayedResponses="20000"

Maximum number of response or forward templates (Velocity, Mustache or JavaScript) that can be queued waiting to be rendered.

Templates are rendered on a dedicated pool of threads (as many as actionHandlerThreadCount). If requests arrive faster than templates can be rendered they queue, and each queued request is held in memory. When the limit is reached, further templated requests are answered straight away with 503 Service Unavailable and a Retry-After: 1 header. As with delayed responses, the request still counts as a match for its expectation and has no response entry in the request log. Rejections are reported in a WARN log line at most every 10 seconds and, when metrics are enabled, counted by the mock_server_overload_rejections metric (with reason="template_actions"); the mock_server_template_action_queued_tasks metric shows the current queue length.

If you see these rejections at a load you expect to handle, simplify the template or raise actionHandlerThreadCount before raising this limit; set it to 0 to restore the previous unlimited behaviour (not recommended).

Type: int Default: maximum heap divided by 64 KB, up to 100,000 (about 8,000 for a 512 MB heap; 1,000 if the JVM reports no heap limit)

Java Code:

ConfigurationProperties.maxQueuedTemplateActions(int maxQueuedTemplateActions)

System Property:

-Dmockserver.maxQueuedTemplateActions=...

Environment Variable:

MOCKSERVER_MAX_QUEUED_TEMPLATE_ACTIONS=...

Property File:

mockserver.maxQueuedTemplateActions=...

Example:

-Dmockserver.maxQueuedTemplateActions="20000"

Number of threads for client event loop when calling downstream

These threads are used for fast non-blocking activities such as, reading and de-serialise all requests and responses

Type: int Default: 5

Java Code:

ConfigurationProperties.clientNioEventLoopThreadCount(int count)

System Property:

-Dmockserver.clientNioEventLoopThreadCount=...

Environment Variable:

MOCKSERVER_CLIENT_NIO_EVENT_LOOP_THREAD_COUNT=...

Property File:

mockserver.clientNioEventLoopThreadCount=...

Example:

-Dmockserver.clientNioEventLoopThreadCount="5"

Number of threads for each expectation with a method / closure callback (i.e. web socket client) in the org.mockserver.client.MockServerClient

This setting only effects the Java client and how requests each method / closure callbacks it can handle, the default is 5 which should be suitable except in extreme cases.

Type: int Default: 5

Java Code:

ConfigurationProperties.webSocketClientEventLoopThreadCount(int count)

System Property:

-Dmockserver.webSocketClientEventLoopThreadCount=...

Environment Variable:

MOCKSERVER_WEB_SOCKET_CLIENT_EVENT_LOOP_THREAD_COUNT=...

Property File:

mockserver.webSocketClientEventLoopThreadCount=...

Example:

-Dmockserver.webSocketClientEventLoopThreadCount="5"

Maximum time allowed in milliseconds for any future to wait — for example when waiting for a response over a method / closure callback (web socket), and as the outer cap on every forward/proxy wait (including maxSocketTimeoutInMillis and socketConnectionTimeoutInMillis): whichever of this value or the more specific timeout is reached first ends the wait. Raise it if you also raise those timeouts past 90 seconds, otherwise the forward still times out at this value regardless.

Type: long Default: 90000

Java Code:

ConfigurationProperties.maxFutureTimeout(long milliseconds)

System Property:

-Dmockserver.maxFutureTimeout=...

Environment Variable:

MOCKSERVER_MAX_FUTURE_TIMEOUT=...

Property File:

mockserver.maxFutureTimeout=...

Example:

-Dmockserver.maxFutureTimeout="90000"

Also accepted under the unit-bearing name maxFutureTimeoutInMillis / MOCKSERVER_MAX_FUTURE_TIMEOUT_IN_MILLIS, which matches the Java API (Configuration.maxFutureTimeoutInMillis()) and the value reported in the configuration JSON. The two names are the same setting; set whichever you prefer.

If true (the default) request matchers will fail on the first non-matching field, if false request matchers will compare all fields.

Set to false when debugging matching issues to see all mismatching fields in a single log entry. See Troubleshooting Matching for a step-by-step guide.

Type: boolean Default: true

Java Code:

ConfigurationProperties.matchersFailFast(boolean enable)

System Property:

-Dmockserver.matchersFailFast=...

Environment Variable:

MOCKSERVER_MATCHERS_FAIL_FAST=...

Property File:

mockserver.matchersFailFast=...

Example:

-Dmockserver.matchersFailFast="false"

Internal performance tuning knob, not part of the standard configuration set. Below this many registered expectations, request matching always runs the plain linear scan; at or above it, MockServer engages an internal candidate index that narrows the scan for literal method+path expectation sets. The default of 64 keeps small/common expectation sets on the unchanged linear scan while large ones get the speed-up. You should not normally need to change this; it exists for benchmarking and for tuning very large expectation sets.

Values below 2 are raised to 2 (a store of 0 or 1 expectations can never benefit from the index). This is a JVM system property only — it has no environment-variable or properties-file form, and setting it in either of those is reported as ignored, with the correct -D form suggested. It is also read once per request-matcher construction, so changing it on a running server has no effect.

Type: int Default: 64 (JVM system property only; no Java API)

System Property:

-Dmockserver.candidateIndexThreshold=...

Example:

-Dmockserver.candidateIndexThreshold="100"

Maximum request body size in bytes that conversation-aware LLM matchers will parse. LLM conversation matchers (whenLatestMessageContains, whenContainsToolResultFor, etc.) parse the inbound request body as JSON to extract the message history. For deep conversation histories or large tool results, this parse step is proportional to body size.

Requests whose body exceeds this cap skip conversation-aware matching and are treated as a no-match for conversation predicates (the scenario state machine is unaffected). Increase this value only when your LLM conversations regularly include very large tool results or long message histories. Reduce it in memory-constrained environments to bound the maximum allocation per matching attempt. Values outside the supported range are clamped to the nearest limit whenever the setting is read, and an INFO log entry names the clamped value.

Type: int Default: 1048576 (1 MiB) Range: 16384 (16 KiB) — 67108864 (64 MiB)

Java Code:

ConfigurationProperties.maxLlmConversationBodySize(int size)

Configuration.maxLlmConversationBodySize(Integer size)

System Property:

-Dmockserver.maxLlmConversationBodySize=...

Environment Variable:

MOCKSERVER_MAX_LLM_CONVERSATION_BODY_SIZE=...

Property File:

mockserver.maxLlmConversationBodySize=...

Example:

-Dmockserver.maxLlmConversationBodySize="4194304"

Allowlist of custom load-scenario label names (comma-separated) that are added as extra, fixed Prometheus labels on the mock_server_load_* metrics. Prometheus requires a fixed label-name set at registration time, so only the keys named here are exposed as Prometheus labels on those metrics — any custom label a scenario or step sets via withLabels(...) that is not listed here is silently dropped from Prometheus output, though every custom label is always attached as an OpenTelemetry attribute regardless of this setting.

When empty (the default), the Prometheus load metrics carry only the fixed structured labels (scenario, run_id, step, route, method, status_class). Set it once at startup to the label keys your load scenarios use (e.g. env,region,team) so they appear as Prometheus labels; it cannot be changed per-scenario because Prometheus label sets are fixed per metric. See Observability & Metrics for the full load-testing metrics reference.

Type: string (comma-separated) Default: "" (empty — no extra Prometheus labels)

Java Code:

ConfigurationProperties.loadGenerationMetricLabels(String labels)

System Property:

-Dmockserver.loadGenerationMetricLabels=...

Environment Variable:

MOCKSERVER_LOAD_GENERATION_METRIC_LABELS=...

Property File:

mockserver.loadGenerationMetricLabels=...

Example:

-Dmockserver.loadGenerationMetricLabels="env,region,team"

The port (or comma-separated list of ports) MockServer listens on for incoming requests. Port unification means the same port serves HTTP, HTTPS, and proxying (forward, transparent, and binary) traffic simultaneously — there is no separate proxy port to configure. Each port given starts its own listener; set several to bind more than one port, for example to run a mock on one port and a transparent proxy on another.

Set it when starting the server (CLI argument, system property, environment variable, properties file, or the port arguments passed to ClientAndServer.startClientAndServer(...) / the ClientAndServer and MockServer constructors). See Running MockServer for every way to start it.

Type: int (or comma-separated list) Default: required for the command line, Docker, and the Maven plugin — the official Docker image sets it to 1080

CLI Argument:

-p 1080

System Property:

-Dmockserver.serverPort=...

Environment Variable:

MOCKSERVER_SERVER_PORT=...

Property File:

mockserver.serverPort=...

Docker:

docker run -d --rm -p 1080:1080 -e MOCKSERVER_SERVER_PORT=1080 mockserver/mockserver

Example (multiple ports):

-p 1080,1081

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). When enabled, MockServer also advertises the HTTP/3 endpoint via an Alt-Svc header on all TCP (HTTP/1.1 and HTTP/2) responses so HTTP/3-capable clients automatically upgrade to QUIC (see http3AdvertiseAltSvc and http3AltSvcMaxAge). Requires the BoringSSL/QUIC native library, which is not included in the default standalone jar — the Docker image mockserver/mockserver:<version> includes it (the -http3 tags and Helm image.variant=http3 are deprecated aliases of it), otherwise use the jar-with-dependencies-http3 jar or the no-dependencies jar (which include it), or add io.netty:netty-codec-native-quic for your platform. If this property is set and that library is missing, MockServer fails to start with a message naming the fixes for your version and platform (earlier versions logged a warning and started without the HTTP/3 listener). MockServer also fails to start if the HTTP/3 listener cannot be started on this port, most often because the UDP port is already in use: it reports one line naming the port and the cause, where earlier versions logged a warning and served only HTTP/1.1 and HTTP/2. The usual holder is another MockServer given the same value (two embedded servers in one JVM, parallel test forks sharing one mockserver.http3Port, several instances on one host from one properties file): give each its own port, or set it only where HTTP/3 is needed (see HTTP/3 lifecycle). See HTTP/3 (QUIC) Support for details and current limitations.

The HTTP/3 port listens on the address set by Local Bound IP, as the HTTP(S) ports do, or on every address when that is not set.

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"

Experimental. Maximum idle timeout in milliseconds for QUIC connections. After this period of inactivity, the QUIC connection is closed. Increase this value if clients need to keep long-lived idle HTTP/3 connections open (e.g. for SSE or streaming scenarios).

Type: long Default: 5000

Java Code:

ConfigurationProperties.http3MaxIdleTimeout(long millis)

System Property:

-Dmockserver.http3MaxIdleTimeout=...

Environment Variable:

MOCKSERVER_HTTP3_MAX_IDLE_TIMEOUT=...

Property File:

mockserver.http3MaxIdleTimeout=...

Example:

-Dmockserver.http3MaxIdleTimeout="30000"

Experimental. Connection-level flow control limit in bytes for QUIC. This is the maximum amount of data the peer can send across all streams combined before receiving a flow-control update. The default (10 MB) is generous for testing. Reduce this if you want to simulate a constrained connection or increase it for very large request/response bodies.

Type: long Default: 10000000

Java Code:

ConfigurationProperties.http3InitialMaxData(long bytes)

System Property:

-Dmockserver.http3InitialMaxData=...

Environment Variable:

MOCKSERVER_HTTP3_INITIAL_MAX_DATA=...

Property File:

mockserver.http3InitialMaxData=...

Example:

-Dmockserver.http3InitialMaxData="50000000"

Experimental. Per-stream flow control limit in bytes for bidirectional QUIC streams. Applied to both local and remote bidirectional streams. Each HTTP/3 request uses one bidirectional stream, so this controls how much request/response data can be in flight per request before flow-control kicks in.

Type: long Default: 1000000

Java Code:

ConfigurationProperties.http3InitialMaxStreamDataBidirectional(long bytes)

System Property:

-Dmockserver.http3InitialMaxStreamDataBidirectional=...

Environment Variable:

MOCKSERVER_HTTP3_INITIAL_MAX_STREAM_DATA_BIDIRECTIONAL=...

Property File:

mockserver.http3InitialMaxStreamDataBidirectional=...

Example:

-Dmockserver.http3InitialMaxStreamDataBidirectional="5000000"

Experimental. Maximum number of concurrent bidirectional streams per QUIC connection. Each HTTP/3 request uses one bidirectional stream. The default (100) allows 100 concurrent requests per connection. Increase this if you need more parallelism per connection.

Type: long Default: 100

Java Code:

ConfigurationProperties.http3InitialMaxStreamsBidirectional(long maxStreams)

System Property:

-Dmockserver.http3InitialMaxStreamsBidirectional=...

Environment Variable:

MOCKSERVER_HTTP3_INITIAL_MAX_STREAMS_BIDIRECTIONAL=...

Property File:

mockserver.http3InitialMaxStreamsBidirectional=...

Example:

-Dmockserver.http3InitialMaxStreamsBidirectional="200"

Experimental. Maximum capacity in bytes of the QPACK dynamic table used for HTTP/3 header compression. QPACK uses a dynamic table to compress frequently repeated headers (similar to HPACK in HTTP/2). Set to 0 (the default) to disable the dynamic table entirely and use only the static table. Enable and increase this when you want HTTP/3 header compression to be more efficient for repeated headers at the cost of additional memory per connection.

Type: long Default: 0 (dynamic table disabled)

Java Code:

ConfigurationProperties.http3QpackMaxTableCapacity(long bytes)

System Property:

-Dmockserver.http3QpackMaxTableCapacity=...

Environment Variable:

MOCKSERVER_HTTP3_QPACK_MAX_TABLE_CAPACITY=...

Property File:

mockserver.http3QpackMaxTableCapacity=...

Example:

-Dmockserver.http3QpackMaxTableCapacity="4096"

Experimental. Max-age in seconds for the Alt-Svc header that MockServer adds to TCP (HTTP/1.1 and HTTP/2) responses when http3Port is set. This tells HTTP/3-capable clients how long to cache the Alt-Svc advertisement. After the max-age expires, clients will re-discover via the next response. Only relevant when http3Port > 0 and http3AdvertiseAltSvc is true.

Type: long Default: 86400 (24 hours)

Java Code:

ConfigurationProperties.http3AltSvcMaxAge(long seconds)

System Property:

-Dmockserver.http3AltSvcMaxAge=...

Environment Variable:

MOCKSERVER_HTTP3_ALT_SVC_MAX_AGE=...

Property File:

mockserver.http3AltSvcMaxAge=...

Example:

-Dmockserver.http3AltSvcMaxAge="3600"

Experimental. Whether to add an Alt-Svc header advertising HTTP/3 to responses served over the TCP (HTTP/1.1 and HTTP/2) paths when http3Port is set. When true (the default), HTTP/3-capable clients will automatically upgrade to QUIC on subsequent requests and fall back to HTTP/2 or HTTP/1.1 if QUIC is unavailable. Set to false to keep HTTP/3 enabled for direct QUIC clients without advertising it to TCP clients.

Type: boolean Default: true

Java Code:

ConfigurationProperties.http3AdvertiseAltSvc(boolean advertise)

System Property:

-Dmockserver.http3AdvertiseAltSvc=...

Environment Variable:

MOCKSERVER_HTTP3_ADVERTISE_ALT_SVC=...

Property File:

mockserver.http3AdvertiseAltSvc=...

Example:

-Dmockserver.http3AdvertiseAltSvc="false"

Experimental. Enable the CONNECT-UDP (MASQUE, RFC 9298) forward proxy on the HTTP/3 server. When enabled, the server advertises SETTINGS_ENABLE_CONNECT_PROTOCOL (RFC 9220) and extended-CONNECT requests with :protocol=connect-udp are relayed: MockServer opens a UDP socket to the target authority and forwards datagrams in both directions, so an HTTP/3 client can tunnel UDP through MockServer. Normal (non-CONNECT) HTTP/3 requests are unaffected regardless of this setting.

Security — restrict the relay target. By default the relay can reach any UDP host:port reachable from MockServer (including private networks, loopback, and cloud metadata endpoints such as 169.254.169.254), so it is intended for controlled test environments only. To constrain it, set http3ConnectUdpAllowedTargets (an allowlist) and/or enable forwardProxyBlockPrivateNetworks (which now also blocks private/loopback/metadata CONNECT-UDP targets, exactly as it does for forwarded requests). Even so, leave CONNECT-UDP disabled (the default) unless needed and do not expose a CONNECT-UDP–enabled HTTP/3 port to untrusted clients.

Type: boolean Default: false

Java Code:

ConfigurationProperties.http3ConnectUdpEnabled(boolean enabled)

System Property:

-Dmockserver.http3ConnectUdpEnabled=...

Environment Variable:

MOCKSERVER_HTTP3_CONNECT_UDP_ENABLED=...

Property File:

mockserver.http3ConnectUdpEnabled=...

Example:

-Dmockserver.http3ConnectUdpEnabled="true"

Experimental. Restrict which targets the HTTP/3 CONNECT-UDP (MASQUE) relay may reach, as a comma-separated allowlist of host or host:port entries (bracket IPv6 literals, e.g. [::1]:53). Matching is exact and case-insensitive; an entry without a port permits the host on any port. Only relevant when http3ConnectUdpEnabled is true.

When empty (the default) the allowlist is not enforced and the relay may reach any target (still subject to forwardProxyBlockPrivateNetworks). When set, a CONNECT-UDP request to a target that does not match any entry is refused with 403 and no datagrams are relayed — use this to limit the relay's SSRF exposure to a known set of destinations.

Type: string Default: "" (not enforced)

Java Code:

ConfigurationProperties.http3ConnectUdpAllowedTargets(String allowedTargets)

System Property:

-Dmockserver.http3ConnectUdpAllowedTargets=...

Environment Variable:

MOCKSERVER_HTTP3_CONNECT_UDP_ALLOWED_TARGETS=...

Property File:

mockserver.http3ConnectUdpAllowedTargets=...

Example:

-Dmockserver.http3ConnectUdpAllowedTargets="dns.example.com:53,[::1]:9090"

Maximum time in milliseconds to wait for the first response byte when forwarding/proxying. It also limits how long a proxied WebSocket upgrade waits for the upstream server's handshake response; a client whose upstream does not answer in time receives a 502 Bad Gateway. Each wait is also capped by maxFutureTimeout.

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"

Also accepted under the unit-bearing name maxSocketTimeoutInMillis / MOCKSERVER_MAX_SOCKET_TIMEOUT_IN_MILLIS, which matches the Java API and the value reported in the configuration JSON. The two names are the same setting; set whichever you prefer.

Maximum time in milliseconds allowed to connect to a socket. When a TLS (HTTPS) connection is established this also bounds the TLS handshake — both inbound handshakes MockServer terminates (direct HTTPS and CONNECT tunnels) and outbound handshakes to a TLS upstream when forwarding or proxying, for HTTP, binary (non-HTTP) and proxied WebSocket (wss) traffic alike — so it covers the whole connect-and-handshake window rather than the TCP connection alone. For an inbound TLS connection it applies twice: once to receiving the client's first handshake message (the ClientHello) and generating a certificate for it, and again to the rest of the handshake, so a client can hold a handshake open for at most twice this value. Lower it to stop a slow or malicious client holding a handshake open; the default is more lenient than Netty's built-in 10,000ms handshake timeout. For an inbound handshake a value of 0 or less keeps Netty's 10,000ms.

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"

Also accepted under the unit-bearing name socketConnectionTimeoutInMillis / MOCKSERVER_SOCKET_CONNECTION_TIMEOUT_IN_MILLIS, which matches the Java API and the value reported in the configuration JSON. The two names are the same setting; set whichever you prefer.

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"

An HTTP/1.1 client can send several requests on one connection without waiting for each response (pipelining). The responses must come back in the order the requests were sent, because the client pairs each response with a request by its position.

When true, MockServer handles one request on a connection at a time: a pipelined request waits until the response to the request ahead of it has been written. Responses therefore always come back in order, but pipelined requests on one connection are no longer handled at the same time, so the total time is the sum of their delays rather than the longest one. A request waiting behind a paused breakpoint or a streamed response is not recorded until its turn. Clients that do not pipeline (browsers, curl and most HTTP libraries by default) see no difference. A connection holding requests behind a response that makes no progress at all is closed after the idle connection timeout, so a lost response cannot hold them open forever.

When false, each pipelined request is handled as soon as it arrives, as in earlier versions, and a fast response can be written before a slower one sent ahead of it, which the client then pairs with the wrong request.

The setting is read when a connection is opened, so a change affects new connections only. HTTP/2 and HTTP/3 are not affected: each request has its own stream. This property is a temporary rollback switch and will be removed in the next minor release.

Type: boolean Default: true

Java Code:

ConfigurationProperties.http1PipeliningInOrder(boolean inOrder)

System Property:

-Dmockserver.http1PipeliningInOrder=...

Environment Variable:

MOCKSERVER_HTTP1_PIPELINING_IN_ORDER=...

Property File:

mockserver.http1PipeliningInOrder=...

Example:

-Dmockserver.http1PipeliningInOrder="false"

The local IP address MockServer listens on. It applies to every listener: the HTTP(S) ports, the DNS port and the HTTP/3 port. Set it to 127.0.0.1 to keep MockServer off the network, so that only programs on the same host can reach it.

Earlier versions applied it to the HTTP(S) ports only: the DNS and HTTP/3 ports, which use UDP, listened on every address even when it was set.

Type: string Default: "" (empty string; binds to all interfaces, equivalent to 0.0.0.0)

Default changing in a future major release. The default is expected to become 127.0.0.1, so MockServer is reachable only from the same machine unless you choose otherwise. In a container, or wherever other machines must reach MockServer, set MOCKSERVER_LOCAL_BOUND_IP=0.0.0.0. While this property is not set, MockServer logs a warning at startup saying so; set it to either value to keep the behaviour you want and remove the warning.

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"

By default MockServer matches the request method, path and regex body case-insensitively, so an expectation for path /Path also matches a request to /path. Enable this setting to make matching of those fields case-sensitive (exact case), so /Path only matches /Path. (Exact string bodies are already matched case-sensitively, so they are unaffected by this setting.)

This also affects response verification: when enabled, the response reason-phrase matcher in a verification (httpResponse.reasonPhrase) is also compared case-sensitively.

This only affects the request method, path, string/regex body, and response reason-phrase. Header names and values, cookie names and values, and query string parameters are always matched case-insensitively regardless of this setting (HTTP header names in particular are case-insensitive by specification, and some web containers normalise their case).

Type: boolean Default: false

Java Code:

ConfigurationProperties.matchExactCase(boolean enable)

System Property:

-Dmockserver.matchExactCase=...

Environment Variable:

MOCKSERVER_MATCH_EXACT_CASE=...

Property File:

mockserver.matchExactCase=...

Example:

-Dmockserver.matchExactCase="true"

Maximum size in bytes of the first line of an HTTP/1.1 request (the method, the URL with its query string, and the protocol version)

A longer request line is answered with 414 Request-URI Too Long and the connection is closed; the request is not matched against any expectation. The default, 64 KB, is well above what web servers and load balancers usually accept (8 KB to 16 KB). Raise it if you deliberately send longer URLs; set 2147483647 to remove the limit, which lets a client that never ends its request line make MockServer hold it in memory. Zero or a negative value is read as 1.

This also limits each chunk-size line of a chunked HTTP/1.1 request body (the chunk size and any chunk extensions). Whatever value is set, MockServer rejects a chunk-size line once more than 8 KiB of it is waiting to be read, with a 400 response, and closes the connection.

HTTP/2 and HTTP/3 requests have no request line: their URL is counted with their headers, against the maximum header size.

Type: int Default: 65536

Default changing in a future major release. The default is expected to become 8192 (8 KB), the value most web servers and load balancers use. While this property is not set, MockServer logs a warning at startup saying so; set it to any value to keep the behaviour you want and remove the warning.

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 in bytes of the headers of a request, all headers counted together, over HTTP/1.1, HTTP/2 and HTTP/3; also the most MockServer reads of an upstream server's response headers when it forwards or proxies

A request with larger headers is refused and is not matched against any expectation. The default, 256 KB, is well above what web servers and load balancers usually accept (8 KB to 64 KB) and fits large cookies and authentication tokens. Raise it if you deliberately send larger headers; set 2147483647 to remove the limit, which lets a client that keeps sending headers make MockServer hold them in memory. Zero or a negative value is read as 1.

How an over-limit request is refused depends on the protocol:

• HTTP/1.1: 431 Request Header Fields Too Large, and the connection is closed.
• HTTP/2: 431 on that request's stream, which is then reset; other requests on the connection carry on. If the headers as sent (compressed) are more than a quarter over the limit, the connection is closed instead.
• HTTP/3: the connection is closed with the error H3_EXCESSIVE_LOAD; no 431 is sent.

Over HTTP/2 and HTTP/3 the size is counted the way those protocols define it: the name and value of every header plus 32 bytes each, including the method, host and URL (which are headers in those protocols), after decompression. A request with a long URL or a great many small headers therefore reaches the limit sooner over HTTP/2 or HTTP/3 than over HTTP/1.1. MockServer tells HTTP/2 and HTTP/3 clients the limit when they connect, and some clients will not send a larger request at all.

The same limit applies to the responses MockServer reads when it forwards or proxies a request: the headers of the upstream server's response, and its trailers, can be up to this size, over HTTP/1.1 and HTTP/2, so large Set-Cookie, Content-Security-Policy or token headers pass through. A response with larger headers is not passed on: the client is answered 502 with the reason as the body (for example upstream response headers are larger than maxHeaderSize (262144 bytes)), and it is logged once at WARN. When requests are sent through an upstream proxy (forwardHttpsProxy), the proxy's reply to CONNECT is limited the same way. So is an upstream server's reply to a WebSocket handshake that MockServer proxies: with larger headers the WebSocket is not opened and the client is answered 502. Before this, MockServer read at most 8 KB of an upstream's response headers whatever this was set to; if you have set it lower than 8192, upstream response headers are now limited to that lower value too. Mocked responses are not limited.

A request MockServer accepts can still be larger than the server it is forwarded to allows. MockServer sends it and passes on that server's answer, usually 431. Before, when forwarding over HTTP/2 on a connection where the server had already announced a smaller limit, MockServer did not send the request and answered 502.

Before this setting applied to HTTP/2 and HTTP/3, their headers were limited to 8 KB whatever it was set to. To restore that, set maxHeaderSize to 8192, which limits HTTP/1.1 headers to 8 KB too.

The trailers of an HTTP/2 or HTTP/3 request are limited like its headers, and a request with larger trailers is not matched either. Over HTTP/2 that request's stream is reset and other requests on the connection carry on; through a CONNECT or SOCKS tunnel a 431 is sent first if no response has started. Over HTTP/3 the connection is closed with H3_EXCESSIVE_LOAD.

This also limits the trailers that can follow a chunked HTTP/1.1 request body. Whatever value is set, MockServer rejects trailers once more than 8 KiB of them is waiting to be read, with a 400 response, and closes the connection.

Type: int Default: 262144

Default changing in a future major release. The default is expected to become 16384 (16 KB). Requests with very large cookies or tokens may need more: set this property to keep a higher limit. While this property is not set, MockServer logs a warning at startup saying so; set it to any value to keep the behaviour you want and remove the warning.

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

Default changing in a future major release. The default is expected to become 16384 (16 KB). While this property is not set, MockServer logs a warning at startup saying so; set it to any value to keep the behaviour you want and remove the warning.

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. When an HTTP/1.1 connection closes after the 413 (the request asked for Connection: close, or its body had already started arriving), MockServer keeps reading and discarding the rest of the body until the client closes, or for up to 5 seconds, so a client that sends its whole body before reading still receives the 413 instead of a connection 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.

Through a CONNECT tunnel this also limits how much of a streamed response (for example Server-Sent Events) may wait to be written to the client once decompressed; past it the stream is stopped and the client receives an incomplete response.

With binaryMessageFraming set to a protocol, it is also the largest binary message MockServer holds while waiting for the rest of it: a connection that declares a longer message is closed.

The smallest limit is 1 byte. Zero or a negative value is treated as 1, so only requests with an empty or one-byte body are accepted; it never means "no limit".

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 size (in bytes) of a single decoded gRPC message. A request message larger than this is rejected with grpc-status: 8 (RESOURCE_EXHAUSTED) — the status the gRPC specification uses for exceeding the receive-message-size limit, so your client can tell "message too big" apart from "the server broke".

Type: int Default: 4194304 (4 MiB)

The default matches gRPC-Java and gRPC-Go, so a message MockServer accepts is one a real gRPC server would accept too. The limit is also applied while decompressing, so a small compressed message cannot expand past it.

This is separate from maxRequestBodySize, which bounds the whole HTTP body: one HTTP body can carry several gRPC messages (client streaming), and this limit applies to each message. Raise it only if you intentionally mock large gRPC messages — it is what stops a declared message length from allocating unbounded memory.

Java Code:

ConfigurationProperties.maxGrpcMessageSize(int size)

System Property:

-Dmockserver.maxGrpcMessageSize=...

Environment Variable:

MOCKSERVER_MAX_GRPC_MESSAGE_SIZE=...

Property File:

mockserver.maxGrpcMessageSize=...

Example:

-Dmockserver.maxGrpcMessageSize="16777216"

Maximum aggregated body size (in bytes) accepted on responses received from upstream servers when MockServer is acting as a proxy or forwarder.

A streamed response (for example Server-Sent Events, text/event-stream) is passed to the client as it arrives, so its total size is not limited; instead this limits how much of it, once decompressed, may wait to be written to a client that reads more slowly than the upstream sends. Past it MockServer stops the stream and the client receives an incomplete response. MockServer reads more of the upstream only once the client has taken nearly all of what is waiting, so a slow client holds the upstream back rather than filling memory; only a response that decompresses to nearly this limit or more from a single network read, such as a compression bomb, is stopped. Waiting for a slow client does not count towards the streaming response idle timeout. A streamed response in a Content-Encoding MockServer does not decompress (for example br without the Brotli4j library, or a list of codings) is passed on still encoded, with its Content-Encoding.

The smallest limit is 1 byte. Zero or a negative value is treated as 1, so only responses with an empty or one-byte body are passed on; it never means "no limit".

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"

Controls whether JSON Schema body matchers are permitted to fetch remote $ref URIs (http, https, file, jar). By default MockServer blocks remote resolution to prevent server-side request forgery (SSRF): a schema body that contains "$ref": "https://attacker.example/evil.json" would otherwise cause MockServer to make an outbound HTTP request when matching any incoming request against that expectation. Schemas that use only inline definitions or internal anchors (#/...) are unaffected by this setting.

Set to true only when you control all schema $ref URIs and genuinely need cross-document resolution.

Note: this property is read from the JVM system property at schema-build time via System.getProperty; it is not available as an environment variable or in a properties file.

Type: boolean Default: false

System Property:

-Dmockserver.jsonSchemaAllowRemoteRefs=...

Example:

-Dmockserver.jsonSchemaAllowRemoteRefs="true"

When enabled, if no expectation matches an incoming request the 404 response carries the verbose closest-match diagnostic: an x-mockserver-closest-match header plus a JSON body describing which expectation came closest to matching and which fields differed. This lets you see why a mock did not match directly from the response, without checking the MockServer logs or dashboard.

Useful when debugging in test environments. Leave it disabled (the default) for any production-facing use, as the diagnostic exposes expectation internals in the response body.

This is the verbose, opt-in counterpart of closestMatchHintEnabled (a compact, header-only hint that is on by default). The two use different header names and are independent: if both are enabled an unmatched 404 carries both headers (x-mockserver-closest-match with the JSON body, and x-mockserver-closest-match-hint with the one-line summary).

Type: boolean Default: false

Java Code:

ConfigurationProperties.attachMismatchDiagnosticToResponse(boolean enable)

System Property:

-Dmockserver.attachMismatchDiagnosticToResponse=...

Environment Variable:

MOCKSERVER_ATTACH_MISMATCH_DIAGNOSTIC_TO_RESPONSE=...

Property File:

mockserver.attachMismatchDiagnosticToResponse=...

Example:

-Dmockserver.attachMismatchDiagnosticToResponse="true"

When enabled (the default), if no expectation matches an incoming request the 404 response carries a single concise x-mockserver-closest-match-hint header naming the closest expectation and the first field that differed (for example expectation 1a2b: method did not match (expected POST but was GET)). This answers “why didn’t my mock match?” straight from the response, without opening the MockServer logs or dashboard.

The hint is header-only and length-bounded — it never adds a response body, so it cannot leak large or sensitive expectation contents. That is what makes it safe to enable by default. Its verbose counterpart, attachMismatchDiagnosticToResponse (off by default), additionally writes a full JSON diff body under a different header (x-mockserver-closest-match); the two are independent, so enabling both yields both headers on an unmatched 404.

Finding the closest expectation is bounded so that a flood of unmatched requests stays cheap: MockServer checks at most the first 1,000 expectations, in the order it would serve them, and remembers the result for each method and path until the expectations change. With more than 1,000 expectations the hint names the closest of those 1,000 and ends with ; only the first 1000 expectations were checked, because a closer expectation further down may have been skipped. The attachMismatchDiagnosticToResponse body then carries "truncated": true and expectationsChecked.

Type: boolean Default: true

Set this to false if you need unmatched 404 responses to be byte-for-byte free of the extra header (for example a test that asserts the exact response).

Java Code:

ConfigurationProperties.closestMatchHintEnabled(boolean enable)

System Property:

-Dmockserver.closestMatchHintEnabled=...

Environment Variable:

MOCKSERVER_CLOSEST_MATCH_HINT_ENABLED=...

Property File:

mockserver.closestMatchHintEnabled=...

Example:

-Dmockserver.closestMatchHintEnabled="true"

A directory of files MockServer serves when a GET or HEAD request matches no expectation and is not proxied, like WireMock's __files directory. A request for /assets/site.css is answered with the file assets/site.css inside the directory, with a Content-Type chosen from the file extension (application/octet-stream when the extension is not recognised). A path ending in / serves that folder's index.html. A HEAD request gets the headers and the file's Content-Length without the body.

Expectations always win: a file is only served when nothing matched. Anything that is not served — a missing file, a folder, another method, a control plane path under /mockserver/, or a file larger than 50 MiB — still gets the normal 404. Files are read by a small pool of their own (shared with FILE response bodies), so slow reads never hold up other responses; if more than 1,000 file reads are waiting, the rest get 503 Service Unavailable with a Retry-After: 1 header until it catches up; this is logged at most every 10 seconds and, when metrics are enabled, counted by mock_server_overload_rejections with reason="static_files". When MockServer runs as a WAR, files are read on the servlet container's request thread instead, and this limit does not apply.

Because the request chooses the file, only plain paths inside the directory are served. Paths containing .., encoded or double-encoded separators, backslashes, drive letters or control characters are refused, as are hidden files and folders (any name starting with ., such as .env or .git) and symbolic links that lead outside the directory. Folders are never listed. Still, point it only at a directory whose files anyone who can reach MockServer may read.

This is off by default. It can only be set before MockServer starts (system property, environment variable, properties file or startup configuration); PUT /mockserver/configuration ignores it with a warning. If the directory does not exist when MockServer starts, a warning is logged and unmatched requests get a 404 as usual.

Type: string Default: ""

Java Code:

ConfigurationProperties.staticFilesDirectory(String directory)

System Property:

-Dmockserver.staticFilesDirectory=...

Environment Variable:

MOCKSERVER_STATIC_FILES_DIRECTORY=...

Property File:

mockserver.staticFilesDirectory=...

Example:

-Dmockserver.staticFilesDirectory="/var/mockserver/__files"

When enabled, MockServer rejects forward and proxy targets that resolve to loopback, link-local, RFC 1918 private, IPv6 unique-local, carrier-grade NAT (100.64.0.0/10, which Tailscale also uses), 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.

The check applies to every way MockServer forwards or proxies a request: every forward action (httpForward, forward templates, forwards with a fallback, validating forwards, overridden forwarded requests, and class and object forward callbacks), requests that match no expectation and are proxied on (to the destination the client named, to proxyRemoteHost, or to a proxyPassMappings target), binary forwarding and WebSocket proxying. A refused HTTP request gets a 502 Bad Gateway response, a refused binary or WebSocket connection is closed, and a warning saying which address was blocked is logged. Targets you set in configuration, such as proxyRemoteHost, are checked too, so do not enable this if MockServer must proxy to a private address itself.

The check also applies to requests MockServer sends itself:

• before-action, after-action and step webhooks: a refused webhook is not sent and a warning is logged; a blocking webhook with the FAIL_FAST failure policy makes the response a 502 Bad Gateway, and with BEST_EFFORT the response goes ahead;
• load scenario requests: a refused request is not sent and is counted as a failed request (error kind blocked), and a warning is logged once for the run;
• drift alert webhooks (driftAlertWebhookUrl): a refused alert is not sent and a warning is logged;
• the MCP tools that send requests to a service you name (run_contract_test, run_resiliency_test and run_mcp_contract_test): a refused target is sent nothing, the tool returns an error saying which address was blocked, and a warning is logged; with this enabled these tools do not follow redirects.

The upstream proxies MockServer sends through (forwardHttpProxy, forwardHttpsProxy, forwardSocksProxy) are not checked, because they are how MockServer reaches a destination; the destination itself is checked.

The check also applies when MockServer fetches an OpenAPI spec from a URL, to every remote $ref in a spec, and to every redirect followed while fetching them. A refused fetch makes the spec fail to load, with a message saying which address was blocked. To see these fetches, MockServer wraps the JVM's default java.net.ProxySelector the first time it loads a spec with this enabled: other connections are passed on unchanged, but the wrapper stays for the life of the JVM, a redeployed MockServer WAR adds another one, and if your own code sets the default ProxySelector at the same moment, one of the two settings can be lost. If your code sets its own default ProxySelector, set it before MockServer loads a spec.

When several MockServer instances run in one JVM with different values of this setting (for example, each started with its own Configuration), each instance applies its own value to every spec it loads, including the specs it loads to show expectations in the dashboard and to turn an OpenAPI expectation into expectations. A spec that one instance loaded with the check off is fetched again, with the check, by an instance that has it on.

When MockServer forwards, proxies or sends a request without an upstream proxy, it connects to the exact address it checked, so a host name whose DNS answer changes between the check and the connection (DNS rebinding) cannot be used to reach a blocked address.

A request that matches no expectation and whose Host header names MockServer itself by a name it does not recognise as its own, such as a Docker Compose or Kubernetes service name, is treated as a request to proxy. With this enabled such a request gets a 502 Bad Gateway and a warning, because that name resolves to a private address; before this check applied to proxied requests it got a 404 Not Found. To get the 404 back, add that name to noProxyHosts, or set attemptToProxyIfNoMatchingExpectation to false if MockServer is not used as a proxy.

With an upstream proxy (forwardHttpsProxy or forwardSocksProxy) the check still looks the target's name up where MockServer runs, although the proxy resolves the name itself to connect. A name MockServer cannot resolve is refused, so with this enabled, forwarding by name works only where MockServer can resolve the name too. With forwardHttpProxy the request's Host header, which that proxy is sent as the address to go to, is checked as well.

This setting is fixed at startup: a PUT /mockserver/configuration request cannot change it (a different value is ignored and a warning is logged), so a caller of the control plane cannot switch the protection off. Set it with a system property, environment variable, property file or Configuration before the server starts.

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.

Default changing in a future major release. The default is expected to become true. If you forward or proxy to localhost, a Docker network or Kubernetes service addresses, set it to false. While this property is not set, MockServer logs a warning at startup saying so; set it to either value to keep the behaviour you want and remove the warning.

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"

The only hosts MockServer may send requests to. When set, a forward, a proxied request, a replayed request or a webhook to any other host is refused, exactly as forwardProxyBlockPrivateNetworks refuses one: a refused HTTP request gets a 502 Bad Gateway response, a refused webhook is not sent, a refused binary or WebSocket connection is closed, and a warning saying which host was refused is logged. It applies everywhere that setting does, including fetching an OpenAPI spec from a URL (and its remote $refs and redirects); a spec read from a file or the classpath is not affected.

A comma-separated list in which each entry is one of:

• a host name, such as api.example.com, matched exactly (case and a trailing dot are ignored);
• a domain, such as *.example.com (or .example.com), which matches example.com and every name under it;
• an IP address, such as 203.0.113.7, or a CIDR block, such as 10.0.0.0/8 or fd00::/8.

IP addresses and CIDR blocks are matched against the address a host name resolves to as well as against a target given as an address. An IPv4 address written as IPv6 (::ffff:10.1.2.3 or ::10.1.2.3) is matched as the IPv4 address. When MockServer connects to the target itself (forwards, proxied requests, webhooks, binary and WebSocket proxying, HTTP/3 CONNECT-UDP) it connects to the address it checked, so a name whose DNS answer changes after the check (DNS rebinding) cannot reach an address outside the list. That does not hold in three cases: through an upstream proxy (forwardHttpProxy, forwardHttpsProxy, forwardSocksProxy), which resolves the name itself; for the MCP tools and OpenAPI spec fetches, which look the name up again to connect (normally answered by the JVM's DNS cache with the address checked); and when the lists hold only names, because MockServer then does not look names up to check them.

If forwardProxyDeniedHosts is also set, a host on both lists is refused: the deny list wins. Both lists and forwardProxyBlockPrivateNetworks are applied together, so a host must pass all three.

This setting is fixed at startup: a PUT /mockserver/configuration request cannot change it (a different value is ignored and a warning is logged), so a caller of the control plane cannot widen where MockServer sends requests. An entry that is not a host name, domain, IP address or CIDR block is rejected when it is set; if one reaches MockServer another way, every target is refused until it is fixed.

Type: string Default: "" (any host)

Java Code:

ConfigurationProperties.forwardProxyAllowedHosts(String forwardProxyAllowedHosts)

System Property:

-Dmockserver.forwardProxyAllowedHosts=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_ALLOWED_HOSTS=...

Property File:

mockserver.forwardProxyAllowedHosts=...

Example:

-Dmockserver.forwardProxyAllowedHosts="api.example.com,*.partner.example,203.0.113.0/24"

Hosts MockServer must not send requests to, in the same form as forwardProxyAllowedHosts: host names, domains (*.example.com), IP addresses and CIDR blocks. A forward, proxied request, replayed request or webhook to a listed host is refused in the same way, even when forwardProxyAllowedHosts allows it.

A CIDR block also refuses a host name that resolves into it, which is how to keep names that point at internal addresses out: for example 10.0.0.0/8,169.254.169.254. Listing a name refuses only that name; the same server reached by its address is refused only if the address is listed too. A list that holds any loopback address (such as 127.0.0.0/8 or ::1) refuses every address that reaches MockServer's own machine: all of 127.0.0.0/8, ::1 and the wildcard addresses 0.0.0.0 and ::. To refuse every private and metadata address at once, use forwardProxyBlockPrivateNetworks.

This setting is fixed at startup: a PUT /mockserver/configuration request cannot change it.

Type: string Default: "" (no host)

Java Code:

ConfigurationProperties.forwardProxyDeniedHosts(String forwardProxyDeniedHosts)

System Property:

-Dmockserver.forwardProxyDeniedHosts=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_DENIED_HOSTS=...

Property File:

mockserver.forwardProxyDeniedHosts=...

Example:

-Dmockserver.forwardProxyDeniedHosts="admin.example.com,10.0.0.0/8"

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 true (the default) MockServer sends itself a single warm-up request in the background immediately after it starts listening.

The very first request handled by a freshly started MockServer is noticeably slower than every request after it (typically a few hundred milliseconds) because the code that handles requests is only loaded and initialised the first time it is used. The warm-up request pays that one-off cost in the background so the first request from your test or application — including a readiness poll such as Testcontainers — is fast.

The warm-up runs on a background thread and never delays start up. Leave it enabled unless you want to avoid the single extra loopback request during start up, for example in a tightly locked-down environment where MockServer must not connect to itself.

Type: boolean Default: true

Java Code:

ConfigurationProperties.startupWarmup(boolean enable)

System Property:

-Dmockserver.startupWarmup=...

Environment Variable:

MOCKSERVER_STARTUP_WARMUP=...

Property File:

mockserver.startupWarmup=...

Example:

-Dmockserver.startupWarmup="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"

MockServer decides from the first bytes of each connection. Bytes that cannot be the start of HTTP, TLS, SOCKS or HTTP/2 are decided straight away, however few they are. Bytes that could still be the start of one of those (for example GET with nothing after it) are held for up to one second in case the rest follows. Either way, what is not recognised is treated as binary, or as HTTP if this property is true.

When MockServer is proxying a binary connection to a remote host, a message that matches a binary expectation is answered by MockServer and every other message is forwarded as it is (see matchBinaryExpectationsWhenProxying, which you can turn off to forward every message). Otherwise it is matched against binary expectations, and if none matches MockServer replies with the text unknown message format, only HTTP requests are supported for mocking or HTTP & binary requests for proxying, but request is not being proxied and request is not valid HTTP and closes the connection.

Once a connection is binary, everything sent on it afterwards is treated as binary, with one exception: a TLS handshake. A protocol that starts in the clear and switches to TLS on the same connection is supported when mocking with binary expectations. For example, to mock a PostgreSQL server that accepts TLS: add a binary expectation that answers the 8-byte SSLRequest (00 00 00 08 04 d2 16 2f) with the single byte S, and binary expectations for the messages that follow. When the client then starts its TLS handshake, MockServer answers it with its own certificate, exactly as for a connection that starts with TLS (the same certificates, TLS protocols and client-certificate settings apply), and matches what it decrypts against the binary expectations, replying over TLS. Answer the SSLRequest with N instead and the connection carries on in the clear.

Unless binaryMessageFraming names the protocol (PostgreSQL, MySQL, Redis, or a length prefix you describe), MockServer does not know where a binary protocol's messages begin and end. It treats everything it can read from a binary connection in one go, up to 256 KiB, as one message, however many network reads or TLS records that takes. So a message is matched whole when all of it has arrived by the time MockServer reads it: a session of many small messages followed by a larger one (a query or a result of some kilobytes, for example) is matched message by message, in the clear and over TLS, and so is a connection's first message. Over TLS a message of one TLS record (up to about 16 KiB) is always matched whole, however the network delivers the record. What MockServer matches is still not always what the client meant as one message:

• A message that reaches MockServer over time is matched as two or more messages, none of which has an expectation. That happens to a message larger than 256 KiB; to a message of more than one TLS record (about 16 KiB or more) when the records do not arrive together; and, in the clear, to a message that the client writes in several steps or that the network delivers in several packets with a gap between them. With the client on the same host, messages of up to 16,000 bytes over TLS and 40,000 bytes in the clear were always matched whole in measurements, and larger ones often were not; across a network, a message in the clear larger than one packet (about 1,400 bytes) can arrive in pieces.
• Messages that the client sends one after another without waiting for a reply are matched as one message when they arrive together, which they do when the client writes them in one go. Give one expectation the bytes of all of them, and reply with the bytes of all their replies. This applies to TLS as well: two messages sent as two TLS records are one message when MockServer reads them together.

To mock a message that has no reply, give it a binary expectation whose response has no data: binaryResponse() or binaryResponse(new byte[0]) in Java, or "binaryResponse": {} in JSON (an empty binaryData means the same, and is returned without binaryData when the expectation is retrieved). MockServer then writes nothing and keeps the connection open. A message with no expectation at all gets the "unknown message format" text and the connection is closed, which is harmless for a message such as PostgreSQL's Terminate that ends the session anyway. If the client sends a message that has no reply together with the next message, the two arrive as one message, as described above.

A binary response can have a delay, as an HTTP response can: MockServer then writes the reply that long after the message arrived. Replies on one connection keep the order of the messages they answer, so a reply waits for any earlier reply on the same connection that is still delayed, even if its own delay is shorter or it has none. A message that matches no expectation is answered, and its connection closed, only after the delayed replies before it have been written. A response with no data has nothing to delay.

A client that sends messages but does not read the replies is not read either: once the replies MockServer has not yet been able to write to it pass 32 KiB, MockServer stops reading that client until it has read them, as it does when forwarding. The replies MockServer holds for one client are therefore limited, however much the client sends. Nothing is dropped; a client that writes much more than it reads sees its writes stall, as it would against any server.

The handshake is recognised by its first six bytes. A binary message sent in the clear that begins exactly like a TLS ClientHello is therefore taken for one, and a message of one to five bytes that could be the start of one (most plausibly the single byte 0x16) is held for up to one second before it is delivered. When MockServer is proxying binary messages rather than mocking them, it still answers the handshake itself and forwards each decrypted message on a new TLS connection to the remote host, so a remote server that expects the upgrade request on every connection will not accept them.

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"

How MockServer cuts a binary (non-HTTP) connection into messages before it matches each one against your binary expectations, forwards it or logs it. With RAW, the default, MockServer does not know the protocol and treats what it reads in one go as one message (see Assume All Requests Are HTTP), so a message that arrives over time can be split and messages sent together are joined.

Name the protocol instead and MockServer reads where each message ends from the message itself:

• POSTGRESQL: the length that each PostgreSQL message carries (the start-up message, SSLRequest, GSSENCRequest and CancelRequest have no type byte; every message after the start-up message has one).
• MYSQL: the 3-byte length at the start of each MySQL packet. A packet is one message, except that a payload of 16 MiB or more, which MySQL sends as several full packets and a shorter last one, is one message made of all of them (headers included), as it is one command. A MySQL server speaks first, with its greeting, so to proxy MySQL also set forwardBinaryServerFirstWaitMillis (for example to 250) on a connection that has a forward target (port forwarding, transparent proxy or PROXY protocol): MockServer then opens the upstream connection and relays the server's greeting, and frames the client's packets, so with matchBinaryExpectationsWhenProxying (on by default) each packet can be answered by an expectation or forwarded. Mocking MySQL with no upstream server is not possible, as MockServer cannot send the greeting.
• REDIS: one complete RESP2 or RESP3 value, with everything nested in it (a command is an array of bulk strings), or one inline command line such as PING. Values may nest at most 64 deep.
• LENGTH_PREFIX: a length field you describe with binaryMessageLengthPrefixBytes, binaryMessageLengthPrefixByteOrder, binaryMessageLengthPrefixOffset and binaryMessageLengthIncludesPrefix, for a protocol that starts each message with its length (Thrift's framed transport, MongoDB's wire protocol, DNS over TCP, and many in-house protocols).

With any of them:

• a message is matched as one message however it reaches MockServer: written in several steps, delivered in several packets, spread over several TLS records, or larger than 256 KiB;
• messages sent together, such as an extended-query batch of Parse, Bind, Execute and Sync, or pipelined Redis commands, are matched one by one, so each needs an expectation of its own (one whose binary response has no data for a message with no reply), and their replies are written in the order of the messages;
• it works in the clear and over TLS from the first byte. A TLS handshake part way through is recognised only where a new message would start: for PostgreSQL after an SSLRequest, for MySQL only straight after an SSLRequest packet (a MySQL packet can start with the same bytes as a handshake), and for Redis and length-prefixed messages at any message boundary. Bytes in the middle of a message are never taken for the start of a handshake;
• it applies to proxied connections too, so with matchBinaryExpectationsWhenProxying (on by default) each message is matched or forwarded on its own. What the server sends back is relayed as it arrives; with POSTGRESQL, MockServer follows its messages only to know where each reply ends, for a binary response's upstream (see matchBinaryExpectationsWhenProxying). If the server sends a message whose length PostgreSQL does not allow, MockServer logs a warning and relays everything from then on unchanged.

A message may be at most maxRequestBodySize bytes (10 MiB by default), so a client cannot make MockServer hold more than that for one connection. A connection that declares a longer message, or sends bytes the protocol does not allow (a PostgreSQL length below the minimum, MySQL continuation packets out of sequence, a Redis value without its type byte or CRLF, or nested too deeply, a length prefix shorter than the bytes it must count), is closed at once and a warning is logged. MockServer holds a message until all of it has arrived; the bytes of a message that is not complete when the connection closes are discarded.

The setting applies to every binary connection on every port, so use it on a MockServer that mocks or proxies one protocol only. It is read when a connection is found to be binary, so changing it affects new connections only.

Type: string (RAW, POSTGRESQL, MYSQL, REDIS or LENGTH_PREFIX, in any case; an unrecognised value is logged once and read as RAW) Default: RAW

Java Code:

ConfigurationProperties.binaryMessageFraming(BinaryMessageFraming binaryMessageFraming)

System Property:

-Dmockserver.binaryMessageFraming=...

Environment Variable:

MOCKSERVER_BINARY_MESSAGE_FRAMING=...

Property File:

mockserver.binaryMessageFraming=...

Example:

-Dmockserver.binaryMessageFraming="POSTGRESQL"

With binaryMessageFraming set to LENGTH_PREFIX, how many bytes each message's length field has: 1, 2, 4 or 8. The length is read as an unsigned number.

Type: int (1, 2, 4 or 8; any other value is logged once and read as 4) Default: 4

Java Code:

ConfigurationProperties.binaryMessageLengthPrefixBytes(int binaryMessageLengthPrefixBytes)

System Property:

-Dmockserver.binaryMessageLengthPrefixBytes=...

Environment Variable:

MOCKSERVER_BINARY_MESSAGE_LENGTH_PREFIX_BYTES=...

Property File:

mockserver.binaryMessageLengthPrefixBytes=...

Example:

-Dmockserver.binaryMessageLengthPrefixBytes="2"

With binaryMessageFraming set to LENGTH_PREFIX, the byte order of the length field: BIG_ENDIAN (network byte order, most significant byte first) or LITTLE_ENDIAN.

Type: string (BIG_ENDIAN or LITTLE_ENDIAN, in any case; any other value is logged once and read as BIG_ENDIAN) Default: BIG_ENDIAN

Java Code:

ConfigurationProperties.binaryMessageLengthPrefixByteOrder(java.nio.ByteOrder binaryMessageLengthPrefixByteOrder)

System Property:

-Dmockserver.binaryMessageLengthPrefixByteOrder=...

Environment Variable:

MOCKSERVER_BINARY_MESSAGE_LENGTH_PREFIX_BYTE_ORDER=...

Property File:

mockserver.binaryMessageLengthPrefixByteOrder=...

Example:

-Dmockserver.binaryMessageLengthPrefixByteOrder="LITTLE_ENDIAN"

With binaryMessageFraming set to LENGTH_PREFIX, how many bytes of each message come before its length field, such as a type byte or a magic number. They are part of the message that is matched.

Type: int (zero or more; a negative or non-numeric value is logged once and read as 0) Default: 0

Java Code:

ConfigurationProperties.binaryMessageLengthPrefixOffset(int binaryMessageLengthPrefixOffset)

System Property:

-Dmockserver.binaryMessageLengthPrefixOffset=...

Environment Variable:

MOCKSERVER_BINARY_MESSAGE_LENGTH_PREFIX_OFFSET=...

Property File:

mockserver.binaryMessageLengthPrefixOffset=...

Example:

-Dmockserver.binaryMessageLengthPrefixOffset="1"

With binaryMessageFraming set to LENGTH_PREFIX, whether the length counts the whole message, the bytes before the length field and the field itself included (true, as in MongoDB's wire protocol), or only the bytes after the field (false, as in Thrift's framed transport and DNS over TCP). A connection that declares a whole-message length shorter than the bytes before the body is closed.

Type: boolean Default: false

Java Code:

ConfigurationProperties.binaryMessageLengthIncludesPrefix(boolean binaryMessageLengthIncludesPrefix)

System Property:

-Dmockserver.binaryMessageLengthIncludesPrefix=...

Environment Variable:

MOCKSERVER_BINARY_MESSAGE_LENGTH_INCLUDES_PREFIX=...

Property File:

mockserver.binaryMessageLengthIncludesPrefix=...

Example:

-Dmockserver.binaryMessageLengthIncludesPrefix="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"

If true, MockServer uses a per-stream HTTP/2 multiplex pipeline (Http2FrameCodec + Http2MultiplexHandler) instead of the connection-level adapter for HTTP/2 connections where gRPC descriptors are loaded. This is a prerequisite for true client-streaming and bidirectional-streaming gRPC support (to be enabled in a future release). When enabled, the pipeline re-aggregates stream frames so existing unary and server-streaming gRPC behaviour is unchanged.

Requires gRPC to be enabled with descriptors loaded. When false (the default) or when no gRPC descriptors are loaded, the existing connection-level HTTP/2 adapter is used.

Type: boolean Default: false

Java Code:

ConfigurationProperties.grpcBidiStreamingEnabled(boolean enable)

System Property:

-Dmockserver.grpcBidiStreamingEnabled=...

Environment Variable:

MOCKSERVER_GRPC_BIDI_STREAMING_ENABLED=...

Property File:

mockserver.grpcBidiStreamingEnabled=...

Example:

-Dmockserver.grpcBidiStreamingEnabled="true"

Answer CORS preflight (OPTIONS) requests that no expectation matches, for every path, using the corsAllowOrigin policy. In practice it is always on once a preflight has been received: the first CORS preflight MockServer answers itself turns it on. MockServer's own API answers preflights under its own rule (see which web pages can use MockServer's own API) whatever this is set to.

Type: boolean Default: false

Java Code:

ConfigurationProperties.enableCORSForAPI(boolean enableCORSForAPI)

System Property:

-Dmockserver.enableCORSForAPI=...

Environment Variable:

MOCKSERVER_ENABLE_CORS_FOR_API=...

Property File:

mockserver.enableCORSForAPI=...

Example:

-Dmockserver.enableCORSForAPI="true"

Enable CORS for mocked and proxied responses, using the corsAllowOrigin policy. MockServer's own API always answers trusted pages, whatever this is set to.

Type: boolean Default: false

Java Code:

ConfigurationProperties.enableCORSForAllResponses(boolean enableCORSForAllResponses)

System Property:

-Dmockserver.enableCORSForAllResponses=...

Environment Variable:

MOCKSERVER_ENABLE_CORS_FOR_ALL_RESPONSES=...

Property File:

mockserver.enableCORSForAllResponses=...

Example:

-Dmockserver.enableCORSForAllResponses="true"

The value used for CORS in the access-control-allow-origin header of mocked and proxied responses (when enableCORSForAllResponses is on). When blank, the request's origin is sent back. It does not affect MockServer's own API, the dashboard or the callback WebSocket; use controlPlaneCorsAllowOrigin for those.

Note: To ensure access-control-allow-credentials works correctly, when corsAllowCredentials is true the CORS header access-control-allow-origin will set its value using the origin header on requests instead of corsAllowOrigin property.

Type: string Default: ""

Java Code:

ConfigurationProperties.corsAllowOrigin(String corsAllowOrigin)

System Property:

-Dmockserver.corsAllowOrigin=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_ORIGIN=...

Property File:

mockserver.corsAllowOrigin=...

Example:

-Dmockserver.corsAllowOrigin="*"

The browser origins allowed to use MockServer's own API (every /mockserver/... path), the dashboard's live log and the callback WebSocket, as a comma-separated list such as https://app.example.com, http://ci-browser:8080. An allowed page gets its origin sent back in access-control-allow-origin; any other page's requests and WebSocket connections are refused with 403, and its preflights get no CORS headers.

When blank (the default), pages on localhost, 127.0.0.1 or [::1] (http or https, any port) are allowed. Pages MockServer serves itself, such as the dashboard, are also allowed when MockServer is reached by localhost, an IP address, a single-word name, a name ending in .svc, .svc.cluster.local or .internal, or a controlPlaneTrustedHostSuffixes entry, whatever this is set to (see controlPlaneTrustedHostSuffixes); to open the dashboard at any other name, list its origin here, for example https://mockserver.example.com. * allows every web site to read from and change MockServer through a visitor's browser, so only use it when nothing sensitive can be reached. See which web pages can use MockServer's own API.

It can only be set when MockServer starts: PUT /mockserver/configuration ignores it and logs a warning, so a request to the control plane cannot widen it.

Type: string Default: ""

Java Code:

ConfigurationProperties.controlPlaneCorsAllowOrigin(String controlPlaneCorsAllowOrigin)

System Property:

-Dmockserver.controlPlaneCorsAllowOrigin=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_CORS_ALLOW_ORIGIN=...

Property File:

mockserver.controlPlaneCorsAllowOrigin=...

Example:

-Dmockserver.controlPlaneCorsAllowOrigin="https://app.example.com"

Extra host-name endings, as a comma-separated list such as corp.example, k8s.example, at which a page MockServer serves itself, such as the dashboard, may use MockServer's own API and WebSockets. Use it when your Kubernetes cluster uses a custom domain instead of cluster.local, or when you reach MockServer by a private name such as mockserver.corp.example.

Without it, a page MockServer serves is trusted only when MockServer is reached by localhost, an IP address, a single-word name (a Docker, Compose or Kubernetes short service name) or a name ending in .svc, .svc.cluster.local or .internal. A suffix covers names below it (mockserver.corp.example), not the suffix itself; corp.example, .corp.example and *.corp.example mean the same. A public suffix, under which anyone can register a name, such as com, co.uk or github.io, is rejected: it trusts nothing and MockServer logs an error at startup. MockServer also logs a warning for an entry it cannot use. Only list names public DNS cannot resolve: a malicious site that can make a listed name point at MockServer can use MockServer's API through a visitor's browser (DNS rebinding). Even a private name can be rebound by someone who controls your network's name lookups, so use control-plane authentication where that matters.

It can only be set when MockServer starts: PUT /mockserver/configuration ignores it and logs a warning.

Type: string Default: ""

Java Code:

ConfigurationProperties.controlPlaneTrustedHostSuffixes(String controlPlaneTrustedHostSuffixes)

System Property:

-Dmockserver.controlPlaneTrustedHostSuffixes=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TRUSTED_HOST_SUFFIXES=...

Property File:

mockserver.controlPlaneTrustedHostSuffixes=...

Example:

-Dmockserver.controlPlaneTrustedHostSuffixes="corp.example"

The value used for CORS in the access-control-allow-methods header.

The property default is blank. When blank, MockServer does not send an empty header; it applies a built-in fallback of CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE so the control-plane API and dashboard work cross-origin out of the box. Set this property only if you need a narrower method list.

Type: string Default: "" (effective default: CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE)

Java Code:

ConfigurationProperties.corsAllowMethods(String corsAllowMethods)

System Property:

-Dmockserver.corsAllowMethods=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_METHODS=...

Property File:

mockserver.corsAllowMethods=...

Example:

-Dmockserver.corsAllowMethods="CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE"

Default value used for CORS in the access-control-allow-headers and access-control-expose-headers headers.

In addition to this default value any headers specified in the request header access-control-request-headers also get added to access-control-allow-headers and access-control-expose-headers headers in a CORS response.

The property default is blank. When blank and the preflight request carries no access-control-request-headers header, MockServer applies a built-in fallback of Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization rather than sending an empty header. When blank and the preflight does carry access-control-request-headers, MockServer instead echoes back exactly the headers the browser asked to send. Setting it makes the listed headers always allowed; any headers a preflight requests are still added to them.

Type: string Default: "" (effective default: Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization)

Java Code:

ConfigurationProperties.corsAllowHeaders(String corsAllowHeaders)

System Property:

-Dmockserver.corsAllowHeaders=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_HEADERS=...

Property File:

mockserver.corsAllowHeaders=...

Example:

-Dmockserver.corsAllowHeaders="Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"

The value used for CORS in the access-control-allow-credentials header.

Note: To ensure access-control-allow-credentials works correctly, when corsAllowCredentials is true the CORS header access-control-allow-origin will set its value using the origin header on requests instead of corsAllowOrigin property.

Type: boolean Default: false

Java Code:

ConfigurationProperties.corsAllowCredentials(boolean allow)

System Property:

-Dmockserver.corsAllowCredentials=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_CREDENTIALS=...

Property File:

mockserver.corsAllowCredentials=...

Example:

-Dmockserver.corsAllowCredentials="true"

The value, in seconds, used for CORS in the access-control-max-age header, which tells the browser how long it may cache a CORS preflight (OPTIONS) response before sending another one. Raise it to reduce the number of preflight requests a browser-based client sends against a long-running MockServer instance; the default of 0 tells the browser not to cache preflights at all.

Type: int Default: 0

Java Code:

ConfigurationProperties.corsMaxAgeInSeconds(int maxAgeInSeconds)

System Property:

-Dmockserver.corsMaxAgeInSeconds=...

Environment Variable:

MOCKSERVER_CORS_MAX_AGE_IN_SECONDS=...

Property File:

mockserver.corsMaxAgeInSeconds=...

Example:

-Dmockserver.corsMaxAgeInSeconds=300

Headers that MockServer stamps onto every response it returns — mock responses, the control‑plane / dashboard responses, and forwarded / proxied responses. Use this to add organisation‑wide headers (for example a Server header, a build or trace id, or custom org headers) without repeating them on every individual expectation.

Add‑if‑absent: a default header is only added when the response does not already contain a header with that name (matched case‑insensitively), so a header explicitly set on the matched expectation / response always wins.

Format: a pipe (|) separated list of name=value pairs, for example Server=MockServer|X-Trace-Id=abc123. A header value may itself contain commas (for example Cache-Control=no-cache, no-store) — only | separates headers and only the first = in each pair separates the name from the value. Leading / trailing whitespace around each name and value is trimmed.

Type: string Default: "" (no default response headers are added, so behaviour is unchanged)

Java Code:

ConfigurationProperties.defaultResponseHeaders(String defaultResponseHeaders)

System Property:

-Dmockserver.defaultResponseHeaders=...

Environment Variable:

MOCKSERVER_DEFAULT_RESPONSE_HEADERS=...

Property File:

mockserver.defaultResponseHeaders=...

Example:

-Dmockserver.defaultResponseHeaders="Server=MockServer|X-Trace-Id=abc123"

Set comma separated list of the only classes javascript templates are allowed to use via Java.type(...).

By default javascript templates cannot use any Java class at all. Everything else in a template still works — the full modern JavaScript standard library is available — but Java.type(...) and the java.* globals resolve nothing until you list the classes you want here. This is deliberate: a template that can reach java.lang.Runtime can run OS commands inside the MockServer process, so anyone able to register an expectation could run code on your machine.

If one of your templates needs a Java class, add just that class (or its package). Setting this to * lets templates resolve any class again — only do that when every template you render comes from a source you fully trust.

When set, this takes precedence over javascriptDisallowedClasses. Entries match a class name exactly, or match a whole package when they end in .* (for example java.util.*).

Type: string Default: "" (no Java classes can be used)

Java Code:

ConfigurationProperties.javascriptAllowedClasses(String javascriptAllowedClasses)

System Property:

-Dmockserver.javascriptAllowedClasses=...

Environment Variable:

MOCKSERVER_JAVASCRIPT_ALLOWED_CLASSES=...

Property File:

mockserver.javascriptAllowedClasses=...

Example:

-Dmockserver.javascriptAllowedClasses="java.util.*,java.time.Instant"

Set comma separate list of classes not allowed to be used by javascript templates

Setting this widens the default: instead of "no Java class can be used", templates may then use every class except the ones you list here. That is weaker protection, because a list of banned classes can never be complete — banning java.lang.Runtime still leaves java.lang.ProcessBuilder, and a template can reach other classes indirectly. Prefer javascriptAllowedClasses above, or leave both unset.

Type: string Default: ""

Java Code:

ConfigurationProperties.javascriptDisallowedClasses(String javascriptDisallowedClasses)

System Property:

-Dmockserver.javascriptDisallowedClasses=...

Environment Variable:

MOCKSERVER_JAVASCRIPT_DISALLOWED_CLASSES=...

Property File:

mockserver.javascriptDisallowedClasses=...

Example:

-Dmockserver.javascriptDisallowedClasses="java.lang.Runtime,java.lang.Class"

Comma-separated list of literal substrings that must not appear in a JavaScript response template's source. Each entry is checked with a plain substring (contains) match against the template text, not a regular expression, so matching is exact and case-sensitive. If any listed string is found anywhere in the template, MockServer refuses to run it and throws before evaluating any JavaScript, rather than running a partially-trusted template — use this as a defence-in-depth denylist (for example blocking getRuntime().exec, ProcessBuilder, or filesystem access patterns) alongside class allow/deny-listing, not instead of it.

Type: string Default: "" (no restriction)

Java Code:

ConfigurationProperties.javascriptDisallowedText(String javascriptDisallowedText)

System Property:

-Dmockserver.javascriptDisallowedText=...

Environment Variable:

MOCKSERVER_JAVASCRIPT_DISALLOWED_TEXT=...

Property File:

mockserver.javascriptDisallowedText=...

Example:

-Dmockserver.javascriptDisallowedText="getRuntime().exec"

Maximum time in milliseconds a JavaScript response template is allowed to run before it is cancelled. A runaway or malicious template (for example one containing an infinite loop) would otherwise pin the worker thread handling that request indefinitely; this cap aborts the evaluation with a clear timeout error instead, so the request fails fast and the thread is freed.

The default of 5000 (5 seconds) is far longer than any legitimate template needs — a normal template evaluates in well under a second — so it will not affect real templates. Increase it only if you run unusually heavy templates, or set it to 0 (or a negative value) to disable the timeout entirely and restore the previous unbounded behaviour.

Type: long Default: 5000

Java Code:

ConfigurationProperties.javascriptTemplateExecutionTimeout(long millis)

System Property:

-Dmockserver.javascriptTemplateExecutionTimeout=...

Environment Variable:

MOCKSERVER_JAVASCRIPT_TEMPLATE_EXECUTION_TIMEOUT=...

Property File:

mockserver.javascriptTemplateExecutionTimeout=...

Example:

-Dmockserver.javascriptTemplateExecutionTimeout="2000"

Maximum time in milliseconds a Velocity template is allowed to run. When the time is up, the template is stopped with a clear timeout error at its next #foreach iteration, macro call, #parse, #evaluate or use of a #define block, so a loop that never ends (for example over [1..2147483647], or loops nested inside each other), a recursive macro or a chain of blocks cannot keep a template thread busy until MockServer is restarted. A single slow Java call made by the template, such as a regular expression that backtracks heavily or a method that walks a very large range, cannot be stopped part-way, and the limit is on time, not memory.

The default of 5000 (5 seconds) is far longer than a normal template needs, so it will not affect real templates. Increase it only if you run unusually heavy templates, or set it to 0 (or a negative value) to remove the limit.

Type: long Default: 5000

Java Code:

ConfigurationProperties.velocityTemplateExecutionTimeout(long millis)

System Property:

-Dmockserver.velocityTemplateExecutionTimeout=...

Environment Variable:

MOCKSERVER_VELOCITY_TEMPLATE_EXECUTION_TIMEOUT=...

Property File:

mockserver.velocityTemplateExecutionTimeout=...

Example:

-Dmockserver.velocityTemplateExecutionTimeout="2000"

If true (the default since 9.0.0), a response or forward template that fails (it throws an error, does not parse, hits its execution timeout, or produces output that is not a valid response or request) answers the request with 500 Internal Server Error, an x-mockserver-template-error: true header and the template error as a plain-text body, with the template line, column and a hint when the engine reports them; for output that is not valid, the body lists what is wrong with it. The same applies to the response template of a forward with overrides. If false (the default before 9.0.0) a response or forward template that throws answers 404 Not Found, which looks the same as a request that matched no expectation, a response template whose output is not a valid response also answers 404 Not Found, a forward template whose output is not a valid request answers 502 Bad Gateway, a forward's response template that fails answers 502 Bad Gateway, and a forward's response template whose output is not valid leaves the upstream response unchanged; the template error is in the log either way.

The 500 makes a template bug obvious. The body carries the template engine's error message or the validation errors, which can quote part of the template or its output, so set it to false if the callers of your mock should not see template details, or if your tests expect the 404 that MockServer answered before 9.0.0.

Type: boolean Default: true

Java Code:

ConfigurationProperties.templateFailureAsServerError(boolean enable)

System Property:

-Dmockserver.templateFailureAsServerError=...

Environment Variable:

MOCKSERVER_TEMPLATE_FAILURE_AS_SERVER_ERROR=...

Property File:

mockserver.templateFailureAsServerError=...

Example:

-Dmockserver.templateFailureAsServerError="false"

If true class loading is not allowed in velocity templates

This is on by default, so a velocity template cannot load Java classes (for example through $request.class.classLoader.loadClass(...)). That matters because a template that can load java.lang.Runtime can run OS commands inside the MockServer process, so anyone able to register an expectation could run code on your machine. Ordinary templates — values from the request, the built-in $uuid/$now/$faker helpers, the $json/$xml/$math tools — are unaffected.

Set it to false only if one of your templates genuinely needs to load classes, and only when every template you render comes from a source you fully trust.

Type: boolean Default: true

Java Code:

ConfigurationProperties.velocityDisallowClassLoading(boolean velocityDisallowClassLoading)

System Property:

-Dmockserver.velocityDisallowClassLoading=...

Environment Variable:

MOCKSERVER_VELOCITY_DISALLOW_CLASS_LOADING=...

Property File:

mockserver.velocityDisallowClassLoading=...

Example:

-Dmockserver.velocityDisallowClassLoading="true"

Comma-separated list of literal substrings that must not appear in a Velocity response template's source. Each entry is checked with a plain substring (contains) match, not a regular expression, so matching is exact and case-sensitive. If any listed string is found anywhere in the template, MockServer refuses to run it and throws before evaluating the template — use this as a defence-in-depth denylist (for example blocking request.class or other reflection-style access) alongside class loading restrictions, not instead of them.

Type: string Default: "" (no restriction)

Java Code:

ConfigurationProperties.velocityDisallowedText(String velocityDisallowedText)

System Property:

-Dmockserver.velocityDisallowedText=...

Environment Variable:

MOCKSERVER_VELOCITY_DISALLOWED_TEXT=...

Property File:

mockserver.velocityDisallowedText=...

Example:

-Dmockserver.velocityDisallowedText="request.class"

Comma-separated list of literal substrings that must not appear in a Mustache response template's source. Each entry is checked with a plain substring (contains) match, not a regular expression, so matching is exact and case-sensitive. If any listed string is found anywhere in the template, MockServer refuses to run it and throws before evaluating the template — use this as a defence-in-depth denylist, for example {{{,{{& to block both Mustache forms that render a value unescaped (triple braces and {{&name}}), if your templates should never emit raw, unescaped output.

Type: string Default: "" (no restriction)

Java Code:

ConfigurationProperties.mustacheDisallowedText(String mustacheDisallowedText)

System Property:

-Dmockserver.mustacheDisallowedText=...

Environment Variable:

MOCKSERVER_MUSTACHE_DISALLOWED_TEXT=...

Property File:

mockserver.mustacheDisallowedText=...

Example:

-Dmockserver.mustacheDisallowedText="{{{"

Seed for the template faker sample-data helper (Velocity $faker, Mustache {{faker.*}}, JavaScript faker). By default faker is unseeded, so faker-driven templates produce different, random values on every render.

Set a non-zero value to seed faker deterministically so faker-driven templates generate reproducible fixtures across runs — useful when you want your generated test data to be stable from one run to the next. The seed produces a deterministic sequence of values for a given order of renders; determinism is strongest when fixtures are generated sequentially.

The default of 0 leaves faker unseeded, so existing templates are unaffected.

Type: long Default: 0

Java Code:

ConfigurationProperties.templateFakerSeed(long seed)

System Property:

-Dmockserver.templateFakerSeed=...

Environment Variable:

MOCKSERVER_TEMPLATE_FAKER_SEED=...

Property File:

mockserver.templateFakerSeed=...

Example:

-Dmockserver.templateFakerSeed="42"

The environment variables and system properties that templates can read with the systemValue helper (Velocity $systemValue.env('APP_REGION'), JavaScript systemValue.env('APP_REGION'), Mustache {{#systemValue.env}}APP_REGION{{/systemValue.env}}, and property in place of env for a system property). This is the equivalent of WireMock's --permitted-system-keys.

Give a comma-separated list of exact names, such as APP_REGION, or prefixes ending in *, such as APP_*, which allows every name that starts with APP_. Names are case-sensitive and one list covers both environment variables and system properties. A * anywhere other than at the end, or on its own, is ignored with a warning, so you cannot allow every name.

One list covers both environment variables and system properties, so an entry such as app.* also allows an environment variable with that name (and on Windows, where environment variable names ignore case, one that differs only in case). Whatever the list says, templates can never read MockServer's own settings, which can hold passwords and keys: system properties and environment variables whose names start with mockserver. or MOCKSERVER_ (in any case), and the javax.net.ssl.keyStorePassword and javax.net.ssl.trustStorePassword system properties. An entry that names or covers them is reported with a warning when MockServer starts.

The default is empty, so systemValue returns an empty value for every name. A name that is not on the list also returns an empty value, exactly like a name that is not set, so a template cannot tell whether it exists, and a warning naming it is logged once (not on every request). There is no way for a template to list names or values.

Security: anyone who can create expectations can write a template that returns these values, so anyone who can create expectations, call them, or read the MockServer log or dashboard can read the value of every name on this list. Never list secrets such as passwords, tokens or keys, avoid broad prefixes such as java.* or javax.net.ssl.*, and prefer exact names. Each time MockServer starts with a list that is not empty, it logs a warning naming what templates can read.

This can only be set before MockServer starts (system property, environment variable, properties file or startup configuration); PUT /mockserver/configuration ignores it with a warning, so a request to the control plane cannot widen it.

Type: string Default: "" (templates read nothing)

Java Code:

ConfigurationProperties.templateSystemValueAllowList(String allowList)

System Property:

-Dmockserver.templateSystemValueAllowList=...

Environment Variable:

MOCKSERVER_TEMPLATE_SYSTEM_VALUE_ALLOW_LIST=...

Property File:

mockserver.templateSystemValueAllowList=...

Example:

-Dmockserver.templateSystemValueAllowList="APP_*,HOSTNAME,app.version"

The class (and package) used to initialize expectations in MockServer at startup, if set MockServer will load and call this class to initialise expectations when is starts.

Type: string Default: null

Java Code:

ConfigurationProperties.initializationClass(String initializationClass)

System Property:

-Dmockserver.initializationClass=...

Environment Variable:

MOCKSERVER_INITIALIZATION_CLASS=...

Property File:

mockserver.initializationClass=...

Spring @MockServerTest:

@MockServerTest("mockserver.initializationClass=org.mockserver.server.initialize.ExpectationInitializerExample")

Example:

-Dmockserver.initializationClass="org.mockserver.server.initialize.ExpectationInitializerExample"

The path to the json file used to initialize expectations in MockServer at startup, if set MockServer will load this file and initialise expectations for each item in the file when is starts.

The expected format of the file is a JSON array of expectations, as per the REST API format

Type: string Default: null

Java Code:

ConfigurationProperties.initializationJsonPath(String initializationJsonPath)

System Property:

-Dmockserver.initializationJsonPath=...

Environment Variable:

MOCKSERVER_INITIALIZATION_JSON_PATH=...

Property File:

mockserver.initializationJsonPath=...

Example:

-Dmockserver.initializationJsonPath="org/mockserver/server/initialize/initializerJson.json"

The path to the OpenAPI spec file used to initialize expectations in MockServer at startup, if set MockServer will load this file and create expectations for each operation when it starts.

The file can be a YAML (.yaml, .yml) or JSON (.json) OpenAPI v3 specification. MockServer will generate an expectation for each operation defined in the spec, with example responses derived from the schema.

To watch multiple files use file globs as documented here: glob patterns

Type: string Default: null

Java Code:

ConfigurationProperties.initializationOpenAPIPath(String initializationOpenAPIPath)

System Property:

-Dmockserver.initializationOpenAPIPath=...

Environment Variable:

MOCKSERVER_INITIALIZATION_OPENAPI_PATH=...

Property File:

mockserver.initializationOpenAPIPath=...

Example:

-Dmockserver.initializationOpenAPIPath="/config/petstore.yaml"

If enabled the initialization JSON file and OpenAPI file will be watched for changes, any changes found will result in expectations being created, removed or updated by matching against their key.

If two expectations have the same id, in one file or in several files, the last one is kept and is matched in the place of the first one. mockserver lint reports each replaced expectation as DUPLICATE_ID.

The order of expectations in the file is the order in which they are created if they are new, however, re-ordering existing expectations does not change the order they are matched against incoming requests.

Type: boolean Default: false

Java Code:

ConfigurationProperties.watchInitializationJson(boolean enable)

System Property:

-Dmockserver.watchInitializationJson=...

Environment Variable:

MOCKSERVER_WATCH_INITIALIZATION_JSON=...

Property File:

mockserver.watchInitializationJson=...

Example:

-Dmockserver.watchInitializationJson="false"

The interval, in milliseconds, at which a watched initialization JSON / OpenAPI file is polled for changes. Only has an effect when watchInitializationJson is enabled.

Lower it for faster live reloads at the cost of more frequent file reads; raise it to reduce polling overhead. A non-positive value is treated as 1 millisecond.

Type: long Default: 5000 (5 seconds)

Java Code:

ConfigurationProperties.watchInitializationJsonPollPeriodMillis(long milliseconds)

System Property:

-Dmockserver.watchInitializationJsonPollPeriodMillis=...

Environment Variable:

MOCKSERVER_WATCH_INITIALIZATION_JSON_POLL_PERIOD_MILLIS=...

Property File:

mockserver.watchInitializationJsonPollPeriodMillis=...

Example:

-Dmockserver.watchInitializationJsonPollPeriodMillis="1000"

If enabled a failure to load any expectation initializer (a malformed initialization JSON or OpenAPI file, or a broken initialization class) will fail server startup with an exception, instead of logging a warning and continuing with zero expectations from that source.

By default (false) a broken initializer is logged once at WARN and MockServer still starts — which can silently leave you with missing mocks in CI or Kubernetes. Enable this when a half-initialized server is worse than a crash, so the failure is loud and visible.

An invalid expectation inside an otherwise valid initialization JSON file (for example a statusCode outside 100 to 999) is skipped with a WARN that names it — its position, id and path — and the rest of the file still loads. With this setting enabled, any skipped expectation also fails startup.

For slow (but valid) initializers, use the readiness probe at GET /mockserver/ready instead, which returns 503 until initialization completes and 200 thereafter.

Type: boolean Default: false

Java Code:

ConfigurationProperties.failOnInitializationError(boolean enable)

System Property:

-Dmockserver.failOnInitializationError=...

Environment Variable:

MOCKSERVER_FAIL_ON_INITIALIZATION_ERROR=...

Property File:

mockserver.failOnInitializationError=...

Example:

-Dmockserver.failOnInitializationError="true"

Enable the persisting of expectations as json, which is updated whenever the expectation state is updated (i.e. add, clear, expires, etc)

When the persisted file is also the file the expectations are loaded from (initializationJsonPath set to the same path, or a cloud blob store restoring it), an expectation in it that could not be loaded would disappear the first time MockServer saves. So before that first save MockServer copies the original file, once, to <file>.invalid-entries-<timestamp>.bak next to it and logs a WARN naming the copy; fix the expectations there and copy them back. If the copy cannot be written, MockServer logs an error and does not save over the file, and tries the copy again on the next save.

Type: boolean Default: false

Java Code:

ConfigurationProperties.persistExpectations(boolean persistExpectations)

System Property:

-Dmockserver.persistExpectations=...

Environment Variable:

MOCKSERVER_PERSIST_EXPECTATIONS=...

Property File:

mockserver.persistExpectations=...

Example:

-Dmockserver.persistExpectations="true"

The file path used to save persisted expectations as json, which is updated whenever the expectation state is updated (i.e. add, clear, expires, etc)

This setting is startup-only: set it before MockServer starts (system property, environment variable, property file or Configuration). A PUT /mockserver/configuration request cannot change it (a different value is ignored and a warning is logged), so a caller of the control plane cannot redirect where MockServer writes files.

Type: string Default: persistedExpectations.json

Java Code:

ConfigurationProperties.persistedExpectationsPath(String persistedExpectationsPath)

System Property:

-Dmockserver.persistedExpectationsPath=...

Environment Variable:

MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=...

Property File:

mockserver.persistedExpectationsPath=...

Example:

-Dmockserver.persistedExpectationsPath="org/mockserver/server/initialize/initializerJson.json"

Enable the persisting of recorded expectations (proxy traffic) as json, which is updated whenever a new request is forwarded through the proxy.

The persisted file can be loaded on restart using initializationJsonPath to replay recorded traffic as mock expectations.

Type: boolean Default: false

Java Code:

ConfigurationProperties.persistRecordedExpectations(boolean enable)

System Property:

-Dmockserver.persistRecordedExpectations=...

Environment Variable:

MOCKSERVER_PERSIST_RECORDED_EXPECTATIONS=...

Property File:

mockserver.persistRecordedExpectations=...

Example:

-Dmockserver.persistRecordedExpectations="true"

The file path used to save persisted recorded expectations as json, which is updated whenever a new request is forwarded through the proxy.

This setting is startup-only: set it before MockServer starts (system property, environment variable, property file or Configuration). A PUT /mockserver/configuration request cannot change it (a different value is ignored and a warning is logged), so a caller of the control plane cannot redirect where MockServer writes files.

Type: string Default: persistedRecordedExpectations.json

Java Code:

ConfigurationProperties.persistedRecordedExpectationsPath(String persistedRecordedExpectationsPath)

System Property:

-Dmockserver.persistedRecordedExpectationsPath=...

Environment Variable:

MOCKSERVER_PERSISTED_RECORDED_EXPECTATIONS_PATH=...

Property File:

mockserver.persistedRecordedExpectationsPath=...

Example:

-Dmockserver.persistedRecordedExpectationsPath="recordedExpectations.json"

When enabled, every recorded exchange — both proxied (FORWARDED_REQUEST log event) and mocked (EXPECTATION_RESPONSE log event) — is appended to an NDJSON file as it completes — one compact JSON object per line (request + response). Lines reach the disk in small batches: as soon as MockServer has caught up with recording, before an import from disk reads the file, and on shutdown. A hard kill loses at most the last few KB of recent lines. The file is opened in append mode, so it survives process restarts and captures the complete session history even as the in-memory event log window evicts old entries under a byte budget.

This is the recommended pairing with maxEventLogSizeInBytes for proxying LLM traffic or any workload with large bodies: disk holds everything durably; memory stays bounded. See Proxying LLM / Large-Body Traffic Without OOM for the full worked example.

Note: disk capture writes the full body before any in-memory truncation (maxLoggedBodyBytes) is applied, so the archive is always complete even when the dashboard shows truncated bodies.

Type: boolean Default: false

Java Code:

ConfigurationProperties.persistRecordedRequestsToDisk(boolean enable)

Configuration.persistRecordedRequestsToDisk(Boolean enable)

System Property:

-Dmockserver.persistRecordedRequestsToDisk=...

Environment Variable:

MOCKSERVER_PERSIST_RECORDED_REQUESTS_TO_DISK=...

Property File:

mockserver.persistRecordedRequestsToDisk=...

Example:

-Dmockserver.persistRecordedRequestsToDisk="true"

The file path for the NDJSON archive written when persistRecordedRequestsToDisk is enabled. The file is opened in append mode on startup, so a fresh session extends the same file. Truncate it manually between sessions, or use --keep-log / omit to start fresh (the launch-with-llm-capture.sh script truncates it automatically unless --keep-log is passed).

This setting is startup-only: set it before MockServer starts (system property, environment variable, property file or Configuration). A PUT /mockserver/configuration request cannot change it (a different value is ignored and a warning is logged), so a caller of the control plane cannot redirect where MockServer writes files.

Type: string Default: recordedRequests.ndjson

Java Code:

ConfigurationProperties.persistedRecordedRequestsPath(String path)

Configuration.persistedRecordedRequestsPath(String path)

System Property:

-Dmockserver.persistedRecordedRequestsPath=...

Environment Variable:

MOCKSERVER_PERSISTED_RECORDED_REQUESTS_PATH=...

Property File:

mockserver.persistedRecordedRequestsPath=...

Example:

-Dmockserver.persistedRecordedRequestsPath="recordedRequests.ndjson"

The maximum number of requests to return in verification failure result, if more expectations are found the failure result does not list them separately

Type: int Default: 10

Java Code:

ConfigurationProperties.maximumNumberOfRequestToReturnInVerificationFailure(Integer maximumNumberOfRequestToReturnInVerificationFailure)

System Property:

-Dmockserver.maximumNumberOfRequestToReturnInVerificationFailure=...

Environment Variable:

MOCKSERVER_MAXIMUM_NUMBER_OF_REQUESTS_TO_RETURN_IN_VERIFICATION_FAILURE=...

Property File:

mockserver.maximumNumberOfRequestToReturnInVerificationFailure=...

Example:

-Dmockserver.maximumNumberOfRequestToReturnInVerificationFailure="20"

When set to true, MockServer generates a unique Certificate Authority (CA) key pair on first startup and saves it to directoryToSaveDynamicSSLCertificate (default: the working directory). This is equivalent to enabling dynamicallyCreateCertificateAuthorityCertificate but is exposed as a single, easy-to-remember flag for proxy setups.

Use this flag for any shared, persistent, or team-facing setup. Without it, MockServer uses the built-in default CA whose private key is published in the MockServer git repository — safe only for isolated local development.

For standalone launches (JAR, Docker, CLI), the startup "Proxy Setup" log block and the mockserver-ca.pem file are written automatically. The CA certificate and proxy configuration are always available on demand from GET /mockserver/proxyConfiguration, regardless of how MockServer was started.

Type: boolean Default: false

Java Code:

ConfigurationProperties.proxySetup(boolean enable)

System Property:

-Dmockserver.proxySetup=...

Environment Variable:

MOCKSERVER_PROXY_SETUP=...

Property File:

mockserver.proxySetup=...

Example:

-Dmockserver.proxySetup="true"

Controls whether MockServer prints a "Proxy Setup" block to the log at startup. The block contains the absolute path to the CA certificate file and the environment variable exports to set (HTTPS_PROXY, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE) in both Unix export and Windows PowerShell $env: forms, ready to paste into a terminal.

The default is false, but the standalone launcher (the executable JAR, Docker image, and mockserver CLI) automatically enables this at startup, so anyone running MockServer as a proxy sees the block without any extra configuration. Embedded usage (new ClientAndServer(...) inside a test suite) stays silent by default to avoid polluting test output on every JUnit run; set this to true explicitly if the block is needed in embedded mode.

When this setting is enabled, MockServer writes the CA certificate to mockserver-ca.pem in the dynamic-SSL directory at startup and prints the "Proxy Setup" log block. When this setting is disabled (e.g. embedded usage), the CA file is instead written on the first call to GET /mockserver/proxyConfiguration. The endpoint itself is always available regardless of this setting.

Type: boolean Default: false (auto-enabled by the standalone launcher)

Java Code:

ConfigurationProperties.proxySetupLogging(boolean enable)

System Property:

-Dmockserver.proxySetupLogging=...

Environment Variable:

MOCKSERVER_PROXY_SETUP_LOGGING=...

Property File:

mockserver.proxySetupLogging=...

Example:

-Dmockserver.proxySetupLogging="true"

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

Default changing in a future major release. The default is expected to become false, so a request that matches no expectation gets a 404 instead of being proxied. If you use MockServer as a proxy, set it to true. While this property is not set, MockServer logs a warning at startup saying so; set it to either value to keep the behaviour you want and remove the warning.

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"

This is how MockServer proxies a binary (non-HTTP) connection; it is not a setting. Each client connection is given one connection to the upstream server, kept for as long as the client's connection lasts, and bytes are passed on in both directions as they arrive. This is what a protocol needs when the server expects a whole session on one connection, for example a database protocol where a client logs in and then sends queries, or when the server sends data the client did not ask for.

Changed in 9.0.0. Until 8.0.0 each message was forwarded on an upstream connection of its own. The settings forwardBinaryRequestsUseSingleConnection and forwardBinaryRequestsWithoutWaitingForResponse were removed in 9.0.0, together with that way of forwarding. A value still set for either, as a system property, environment variable or property-file key, is ignored, and MockServer logs one warning for it at start-up saying it was removed; in a JSON configuration it is ignored without a warning. Remove them from your configuration. A protocol in which every message stands alone works the same on one upstream connection.

What is different from 8.0.0:

• The upstream server sees one connection for each client connection, not one for each message, and that connection stays open for as long as the client's does, even while nothing is sent.
• There is no time limit on the upstream server answering: a client whose upstream never answers stays connected until one side closes. In 8.0.0 the client's connection was closed when no response arrived within maxFutureTimeout. TCP keep-alive (forwardSocketKeepAlive) still detects an upstream server that has gone away.
• The event log has one "returning binary response" entry for each read from the upstream server, including reads that answer no message. In 8.0.0 it had one for each message.
• Everything the upstream server sends is passed to the client, whether or not it answers a message. In 8.0.0 only the first bytes received on each per-message connection were passed on.
• When the upstream server closes its connection, MockServer closes the client's connection, after passing on what the upstream sent, and does not treat that as an error. In 8.0.0 an upstream that closed after answering left the client's connection open, and the client's next message opened a new upstream connection.
• When the client closes its connection, MockServer delivers what the client had already sent and then closes the upstream connection. An upstream server that has stopped reading has its connection closed 5 seconds after the client's close, whether or not it has taken everything.
• A binaryProxyListener is called once for each message read from the client, as soon as it is read, in order, on a thread of its own. In 8.0.0 (without forwardBinaryRequestsWithoutWaitingForResponse) it was called once the response had arrived. The response it is given completes with the first bytes the upstream sends after that message, or with null if the client's next message arrives first or the connection closes. Bytes from the upstream that are not the response to a message (sent unprompted, or after the first bytes of a response) are passed to the listener's onUpstreamMessage method, if it overrides it; a listener that does not is not called for them.
• A client or upstream server that is slower than the other is not buffered in memory: MockServer stops reading from the faster side until the slower side catches up, so a client that sends messages but does not read the replies is not read either. It does the same when more than 64 messages are waiting to be reported to the listener (for onUpstreamMessage it stops reading the upstream server, except while a message is waiting for its response). Nothing is dropped. If the upstream server takes none of the bytes waiting for it for responseWriteStallTimeoutMillis, both connections are closed.
• If forwardProxyBlockPrivateNetworks is on, an upstream address it blocks is refused: the client's connection is closed and a warning is logged. Until 8.0.0 binary forwarding did not make this check.
• If the upstream server cannot be reached, the client's connection is closed and a warning is logged, as before.
• A client that turns TLS on part way through a connection, as a PostgreSQL client does with sslmode=require, can be proxied. What it sends before (PostgreSQL's SSLRequest) goes to the upstream server in the clear and the server's answer comes back; when the client starts TLS, MockServer answers it with its own certificate and starts TLS with the upstream server on the same connection, checking the server's certificate as for any forwarded TLS (forwardProxyTLSX509CertificatesTrustManagerType, forwardProxyTLSCustomTrustX509Certificates, forwardProxyTLSHostnameVerificationEnabled; the default trust type, ANY, accepts any certificate, so set it to JVM or CUSTOM to verify the server's certificate) and presenting forwardProxyPrivateKey / forwardProxyCertificateChain if the server asks for a client certificate. If that handshake fails or takes longer than socketConnectionTimeoutInMillis, both connections are closed and a warning is logged. In 8.0.0 each message the client sent over TLS went on a new upstream connection that started with TLS, which such a server does not accept.
• A client that starts with TLS, from its very first byte, also gets one upstream connection for its whole connection, and that connection starts with TLS too: MockServer answers the client's handshake with its own certificate and makes its own handshake with the upstream server before sending anything, with the same certificate checks, client certificate and time limit as above. If that handshake fails, both connections are closed and a warning is logged. Until 8.0.0 each message went on a new TLS connection of its own, so a server that keeps a session (a database, a message broker) could not be proxied over TLS.
• Through an upstream proxy. If the upstream server is reached through an upstream proxy, the one upstream connection is a tunnel through it, for clear connections and TLS alike, so a session protocol can be proxied through it: SOCKS5 for forwardSocksProxy, and HTTP CONNECT for forwardHttpsProxy or forwardHttpProxy (when both HTTP proxies are set, forwardHttpsProxy is used). If forwardProxyAuthenticationUsername and forwardProxyAuthenticationPassword are set, they are sent with the CONNECT. A server listed in noProxyHosts is connected to directly, and one forwardProxyBlockPrivateNetworks blocks is refused before anything is sent to the proxy. If the proxy refuses the tunnel (for example with 407 Proxy Authentication Required) or cannot be reached, the client's connection is closed and a warning is logged that names the proxy, the setting it came from and the status it answered with. In 8.0.0 a connection whose only upstream proxy was forwardHttpProxy had its bytes sent to the proxy as if it were the server, and a TLS connection, or a clear one with only forwardHttpsProxy set, went to the server directly, around the proxy; an HTTP proxy that does not allow CONNECT to the server's port now refuses the connection instead.
• The name MockServer gives the upstream server over TLS (sent as SNI, and checked against the server's certificate when forwardProxyTLSHostnameVerificationEnabled is on) is the upstream's host name. When the upstream is known only by its IP address (a PROXY protocol header, transparent proxying, or proxyRemoteHost set to an address), it is the name the client sent MockServer, if the client sent one; otherwise no name is sent.

PostgreSQL through MockServer. Clients using sslmode=require work. Because the client sees MockServer's certificate, not the server's, two things behave differently from connecting directly:

• SCRAM channel binding (SCRAM-SHA-256-PLUS, used by default by recent clients when the server offers it over TLS) fails, because it checks the certificate the client sees. Either turn it off in the client (channelBinding=disable for the JDBC driver, channel_binding=disable for libpq and psql), or, if you have the server's certificate and private key, give them to MockServer so it presents the same certificate: set privateKeyPath and x509CertificatePath to them, and certificateAuthorityCertificate to the certificate authority that signed the server's certificate.
• Client certificates cannot be passed through: a server using cert authentication sees MockServer's client certificate.

PostgreSQL 17's direct TLS (sslnegotiation=direct) is not supported.

What is not supported:

• Protocols in which the server speaks first (for example MySQL or SMTP), unless forwardBinaryServerFirstWaitMillis is set. MockServer only knows a connection is binary once the client has sent something, so by default it has not connected upstream before then.
• Binary connections inside a CONNECT or SOCKS tunnel through MockServer. Binary proxying applies where the upstream is fixed: port forwarding (proxyRemotePort), a PROXY protocol header, or transparent proxying.

If true (the default), MockServer answers some messages of a proxied binary connection itself and forwards the rest. Each message the client sends is matched against your binary expectations. A message whose bytes equal an expectation's is answered with that expectation's binary response and is not sent to the upstream server; every other message is forwarded as usual. With no binary expectations, every message is forwarded. Set it to false to forward every message without consulting binary expectations.

Changed in 9.0.0: in 8.0.0 binary expectations were never matched on a proxied connection. If you proxy binary connections and keep binary expectations registered that you do not want to answer proxied messages, set matchBinaryExpectationsWhenProxying to false.

This lets a test use a real server for most of a session and fake one part of it. For example, with a PostgreSQL client in simple query mode and autocommit, you can return a canned result for one SELECT, or an error for one INSERT (with Times.once(), so the client's retry reaches the real server), or give a query no reply at all to test the client's time-out (an expectation whose binary response has no data).

It applies to every proxied binary connection, which is relayed on one upstream connection, directly or through a tunnel of an upstream proxy, forwardHttpProxy included (see Binary Proxying).

What happens upstream to a matched message is chosen per expectation, with the binary response's upstream:

• ANSWER_ONLY (the default): MockServer writes the binary response and does not forward the message.
• ANSWER_AND_FORWARD: MockServer writes the binary response and also forwards the message, so the server still sees it (an INSERT is really made, a PREPARE really exists); the server's reply to that message is dropped.
• FORWARD_AND_REPLACE: MockServer forwards the message and, once the server's reply to it has ended, writes the binary response in its place. The client waits for the real server, so a reply to replace can fake a result while the server keeps its real state. With a delay, the replacement is written no sooner than that long after the message arrived, and the server's later replies wait behind it, so the client gets them in order.

The last two need binaryMessageFraming set to POSTGRESQL, because MockServer must know where the server's reply to one message ends. A reply ends where PostgreSQL says the server waits for the client again: at ReadyForQuery for a simple Query; for an extended-query batch (Parse, Bind, Describe, Execute up to Sync) the whole batch has one reply, ending at the ReadyForQuery after the Sync, so an expectation on the batch's Parse drops or replaces the reply to the whole batch (give the replacement every message the client expects, ParseComplete through ReadyForQuery; a client that sends Flush and waits for an answer before it sends Sync would wait forever for a replacement, so use ANSWER_AND_FORWARD for it); CopyData, Terminate and other messages without a reply have nothing to drop, and a replacement for one is written once the replies before it have ended. Without that framing an expectation that asks for either is answered as ANSWER_ONLY and MockServer logs one warning for the connection. A message matched without an upstream (plain mocking) is always answered as ANSWER_ONLY.

For example, in Java:

mockServerClient
    .when(binaryRequest(queryBytes))
    .respondWithBinary(binaryResponse(cannedRowsBytes).withUpstream(BinaryResponse.Upstream.FORWARD_AND_REPLACE));

or as JSON: "binaryResponse": { "binaryData": "...", "upstream": "FORWARD_AND_REPLACE" }.

Things to know before you rely on it:

• The upstream server never sees a message answered with ANSWER_ONLY. Your canned reply must be true for the state the server is really in. For PostgreSQL that means: reply with the transaction status the session really has (ReadyForQuery with I outside a transaction); do not answer statements whose effect later statements depend on (BEGIN, SET, PREPARE, a Parse for a named statement); do not answer the start-up, authentication or SSLRequest messages.
• A message must arrive exactly as the expectation's bytes. Unless binaryMessageFraming names the protocol, MockServer does not know where a binary protocol's messages begin and end: what it reads in one go is one message (see Assume All Requests Are HTTP). Two messages sent together are one message, and a large message can arrive as several. When the bytes differ in any way there is no match and the bytes are forwarded unchanged, so the session is not broken, but the real server answers. Check in your test that the expectation was matched, not only that the client got an answer. The easiest way to get the exact bytes is to run the client once through MockServer and copy the message from its log.
• Order between MockServer's replies and the server's. Replies from the server reach the client in the order the server sent them, and MockServer's replies in the order of the messages they answer, but nothing orders the two against each other. A client that waits for each reply before sending its next message is not affected. If MockServer writes a reply while a forwarded message has had no response yet, it logs a warning saying the two may reach the client out of order.
• An expectation whose action is not a binary response (for example an HTTP response) does not answer a proxied message: the message is forwarded and a warning is logged.
• An expectation with an empty binary request, or with not, matches every message (or every other message), so nothing (or almost nothing) is forwarded.
• An answered message is logged as it is when mocking without an upstream, and is not reported to a binaryProxyListener, which sees only what was sent to the upstream server. A connection whose messages are all answered opens no upstream connection.
• Cost. A message on a relayed connection is matched against the expectations only when one could match it: when a binary expectation has exactly its bytes, or while a binary expectation without bytes or with not, or a conditional expectation, exists. Every other message is forwarded without being matched, and adds no match or no-match entries to the log; the log still shows each message MockServer received and forwarded. With no binary expectation registered, no message is matched.
• A binary response's delay holds back MockServer's reply as it does without an upstream (see Assume All Requests Are HTTP). Replies from the server are not held behind it, so one can reach the client first; only a FORWARD_AND_REPLACE replacement, which takes the place of a server reply, holds back the server's replies after it.
• A message forwarded with ANSWER_AND_FORWARD or FORWARD_AND_REPLACE is reported to a binaryProxyListener like any forwarded message, with what the server sent. A server message that arrives while a reply is being dropped, such as a notice, is dropped with it.

Type: boolean Default: true

Java Code:

ConfigurationProperties.matchBinaryExpectationsWhenProxying(boolean matchBinaryExpectationsWhenProxying)

System Property:

-Dmockserver.matchBinaryExpectationsWhenProxying=...

Environment Variable:

MOCKSERVER_MATCH_BINARY_EXPECTATIONS_WHEN_PROXYING=...

Property File:

mockserver.matchBinaryExpectationsWhenProxying=...

Example:

-Dmockserver.matchBinaryExpectationsWhenProxying="false"

How long, in milliseconds, MockServer waits for a client to send its first byte before it treats the connection as binary and connects to the upstream server. Set it to proxy a protocol in which the server speaks first, such as MySQL, SMTP or FTP: the client waits for the server's greeting, so without this setting nothing ever happens on the connection. With it, once the client has sent nothing for this long, MockServer opens the upstream connection and passes the greeting, and everything after it, to the client as it arrives. A few hundred milliseconds is usually enough.

It applies only to a connection that has a fixed upstream: port forwarding (proxyRemotePort), a PROXY protocol header, or transparent proxying, through an upstream proxy too (see Binary Proxying). It has no effect when assumeAllRequestsAreHttp is on.

Trade-off: a client that opens a connection and sends HTTP only after this wait (for example a connection pool that opens connections ahead of use) has its connection relayed to the upstream as binary, so its requests are not matched against your expectations. Leave it at 0 on a port that also serves HTTP clients like that.

Type: long Default: 0 (never: a connection waits for its client)

Java Code:

ConfigurationProperties.forwardBinaryServerFirstWaitMillis(long millis)

System Property:

-Dmockserver.forwardBinaryServerFirstWaitMillis=...

Environment Variable:

MOCKSERVER_FORWARD_BINARY_SERVER_FIRST_WAIT_MILLIS=...

Property File:

mockserver.forwardBinaryServerFirstWaitMillis=...

Example:

-Dmockserver.forwardBinaryServerFirstWaitMillis="250"

By default (true) MockServer pools idle keep-alive HTTP/1.1 upstream connections (keyed by host, port and scheme) and reuses them for subsequent requests to the same upstream. Reusing the upstream's keep-alive connections eliminates repeated TCP and TLS handshakes, significantly improves throughput for proxy-heavy workloads that repeatedly call the same upstream, and avoids ephemeral-port exhaustion under sustained forward load (where opening a fresh connection per request can exhaust the operating system's available local ports and cause request failures). Set this to false to open a fresh upstream connection per request that is closed once the response is received (the historical behaviour) — useful only for unusual upstreams.

Pooling is safe to leave on: a connection is only returned to the pool when it is genuinely clean — its HTTP client codec must have no leftover undecoded bytes after the response, and any uncertainty closes the connection instead of pooling it. MockServer's error() action (which deliberately returns raw, non-HTTP bytes and/or drops the connection) — or any malformed upstream reply — is therefore never pooled, so a later request can never reuse a corrupted connection.

HTTP/1.1 keep-alive connections and HTTP/2 connections are pooled (an HTTP/2 connection is reused with a fresh stream per request), so a proxy whose client negotiated HTTP/2 in an HTTPS CONNECT tunnel no longer opens a new upstream connection for every request. HTTP/3, binary forwarding, streaming (Server-Sent Events) responses, and proxy-tunnelled connections are never pooled. A connection the upstream closed, that returned Connection: close, or that returned a reply which did not parse as valid HTTP is never reused and falls back to a fresh connection.

Type: boolean Default: true

Java Code:

ConfigurationProperties.forwardConnectionPoolEnabled(boolean enable)

System Property:

-Dmockserver.forwardConnectionPoolEnabled=...

Environment Variable:

MOCKSERVER_FORWARD_CONNECTION_POOL_ENABLED=...

Property File:

mockserver.forwardConnectionPoolEnabled=...

Example:

-Dmockserver.forwardConnectionPoolEnabled="false"

The maximum number of idle keep-alive upstream connections retained per upstream (host, port and scheme) when connection pooling is enabled. When this limit is reached, surplus connections are closed rather than pooled, so the pool degrades gracefully under load and never blocks. Values below 1 are treated as 1. Only relevant when forwardConnectionPoolEnabled is true.

Type: int Default: 8

Java Code:

ConfigurationProperties.forwardConnectionPoolMaxIdlePerKey(int maxIdlePerKey)

System Property:

-Dmockserver.forwardConnectionPoolMaxIdlePerKey=...

Environment Variable:

MOCKSERVER_FORWARD_CONNECTION_POOL_MAX_IDLE_PER_KEY=...

Property File:

mockserver.forwardConnectionPoolMaxIdlePerKey=...

Example:

-Dmockserver.forwardConnectionPoolMaxIdlePerKey="16"

How long in milliseconds an idle pooled upstream connection is retained before it is closed and evicted when connection pooling is enabled. Set to 0 to disable idle eviction (connections are still discarded when the upstream closes them). Only relevant when forwardConnectionPoolEnabled is true.

Type: long Default: 30000

Java Code:

ConfigurationProperties.forwardConnectionPoolIdleTimeoutMillis(long idleTimeoutMillis)

System Property:

-Dmockserver.forwardConnectionPoolIdleTimeoutMillis=...

Environment Variable:

MOCKSERVER_FORWARD_CONNECTION_POOL_IDLE_TIMEOUT_MILLIS=...

Property File:

mockserver.forwardConnectionPoolIdleTimeoutMillis=...

Example:

-Dmockserver.forwardConnectionPoolIdleTimeoutMillis="60000"

By default, when a burst of forwarded or proxied requests finishes, the pool keeps only up to forwardConnectionPoolMaxIdlePerKey idle connections per upstream and closes the rest. Under very high request rates against a fast upstream (responses returning in well under a millisecond) this can cause connection churn: requests are dispatched faster than earlier connections are returned to the pool, so each opens a fresh connection and the surplus is then closed — capping throughput on connection setup rather than on real work.

Enable this setting to keep those connections warm instead of closing them: idle keep-alive connections are retained on release up to forwardConnectionPoolMaxTotalPerKey per upstream, so the warm pool grows to match the offered concurrency and is then reused, eliminating the churn. Warm connections are still closed and evicted once they have been idle for forwardConnectionPoolIdleTimeoutMillis, so the pool drains back down when load stops.

The default (off) leaves the pool's behaviour exactly as before. Enable it for sustained high-throughput forwarding or load injection against a fast upstream. Only relevant when forwardConnectionPoolEnabled is true.

Type: boolean Default: false

Java Code:

ConfigurationProperties.forwardConnectionPoolKeepAlive(boolean enable)

System Property:

-Dmockserver.forwardConnectionPoolKeepAlive=...

Environment Variable:

MOCKSERVER_FORWARD_CONNECTION_POOL_KEEP_ALIVE=...

Property File:

mockserver.forwardConnectionPoolKeepAlive=...

Example:

-Dmockserver.forwardConnectionPoolKeepAlive="true"

The maximum number of warm (idle) keep-alive upstream connections retained per upstream (host, port and scheme) when forwardConnectionPoolKeepAlive is enabled. This bounds the warm pool so it cannot grow without limit; connections offered beyond this ceiling are closed. The effective ceiling is never below forwardConnectionPoolMaxIdlePerKey (keeping connections warm only ever raises retention, never lowers it). Has no effect unless both forwardConnectionPoolEnabled and forwardConnectionPoolKeepAlive are true.

Type: int Default: 2000

Java Code:

ConfigurationProperties.forwardConnectionPoolMaxTotalPerKey(int maxTotalPerKey)

System Property:

-Dmockserver.forwardConnectionPoolMaxTotalPerKey=...

Environment Variable:

MOCKSERVER_FORWARD_CONNECTION_POOL_MAX_TOTAL_PER_KEY=...

Property File:

mockserver.forwardConnectionPoolMaxTotalPerKey=...

Example:

-Dmockserver.forwardConnectionPoolMaxTotalPerKey="4000"

Enables TCP keepalive (SO_KEEPALIVE) on the connections the forward / proxy client opens to upstream servers. Keepalive lets the operating system detect dead or half-open upstream connections faster (most useful during long-lived or streaming requests) and keeps NAT and firewall connection mappings warm so they are not silently dropped while a pooled connection sits idle. It complements — it does not replace — the connection pool's own liveness checks and idle eviction.

On Linux with the native epoll transport the keepalive timers are tuned (see the idle / interval / count settings below) so a dead peer is detected in about a minute or two rather than the operating-system default of around two hours. On other platforms (macOS, Windows) or when native transport is disabled, only SO_KEEPALIVE is enabled and the operating-system default timers apply.

This is on by default. It is a small, benign change from older versions (which set no keepalive): it is standard for production HTTP clients, costs only an occasional probe packet on otherwise-idle connections, and improves detection of broken upstream connections. Set to false to restore the previous behaviour of no socket keepalive. If you enable keep-warm pooling against a real upstream, also keep forwardConnectionPoolIdleTimeoutMillis below the upstream/NAT idle window so idle connections are reaped before they are silently dropped; keepalive helps detect any that slip through as half-open.

Type: boolean Default: true

Java Code:

ConfigurationProperties.forwardSocketKeepAlive(boolean enable)

System Property:

-Dmockserver.forwardSocketKeepAlive=...

Environment Variable:

MOCKSERVER_FORWARD_SOCKET_KEEP_ALIVE=...

Property File:

mockserver.forwardSocketKeepAlive=...

Example:

-Dmockserver.forwardSocketKeepAlive="false"

How long (in seconds) an upstream connection may sit idle before the first TCP keepalive probe is sent. Only applied on the native epoll transport (Linux) when forwardSocketKeepAlive is enabled. Values below 1 are treated as 1.

Type: int Default: 60

Java Code:

ConfigurationProperties.forwardSocketKeepAliveIdleSeconds(int idleSeconds)

System Property:

-Dmockserver.forwardSocketKeepAliveIdleSeconds=...

Environment Variable:

MOCKSERVER_FORWARD_SOCKET_KEEP_ALIVE_IDLE_SECONDS=...

Property File:

mockserver.forwardSocketKeepAliveIdleSeconds=...

Example:

-Dmockserver.forwardSocketKeepAliveIdleSeconds="120"

How long (in seconds) between successive TCP keepalive probes once probing has started. Only applied on the native epoll transport (Linux) when forwardSocketKeepAlive is enabled. Values below 1 are treated as 1.

Type: int Default: 15

Java Code:

ConfigurationProperties.forwardSocketKeepAliveIntervalSeconds(int intervalSeconds)

System Property:

-Dmockserver.forwardSocketKeepAliveIntervalSeconds=...

Environment Variable:

MOCKSERVER_FORWARD_SOCKET_KEEP_ALIVE_INTERVAL_SECONDS=...

Property File:

mockserver.forwardSocketKeepAliveIntervalSeconds=...

Example:

-Dmockserver.forwardSocketKeepAliveIntervalSeconds="30"

The number of unacknowledged TCP keepalive probes after which an upstream connection is considered dead and closed. Only applied on the native epoll transport (Linux) when forwardSocketKeepAlive is enabled. Values below 1 are treated as 1. With the defaults (idle 60s, interval 15s, count 4) a dead peer is detected roughly 60 + 4×15 = 120 seconds after it goes idle.

Type: int Default: 4

Java Code:

ConfigurationProperties.forwardSocketKeepAliveCount(int count)

System Property:

-Dmockserver.forwardSocketKeepAliveCount=...

Environment Variable:

MOCKSERVER_FORWARD_SOCKET_KEEP_ALIVE_COUNT=...

Property File:

mockserver.forwardSocketKeepAliveCount=...

Example:

-Dmockserver.forwardSocketKeepAliveCount="6"

By default every forwarded request is sent to its upstream over HTTP/1.1, regardless of the protocol the incoming request used. Enable this setting to preserve the incoming request's protocol when forwarding, so a request that arrived over HTTP/2 is forwarded to the upstream over HTTP/2 as well.

HTTP/2 forwarding only happens over TLS using ALPN negotiation. A non-secure (plain HTTP) request is always forwarded over HTTP/1.1 even when this setting is enabled, because HTTP/2 without TLS (h2c) is not supported for forwarding. HTTP/2 upstream connections are pooled and reused across requests (a fresh stream per request) just like HTTP/1.1 connections when connection pooling is enabled.

The default (off) is unchanged from previous behaviour: all forwarded requests use HTTP/1.1.

Type: boolean Default: false

Java Code:

ConfigurationProperties.forwardProxyHttp2Enabled(boolean enable)

System Property:

-Dmockserver.forwardProxyHttp2Enabled=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_HTTP2_ENABLED=...

Property File:

mockserver.forwardProxyHttp2Enabled=...

Example:

-Dmockserver.forwardProxyHttp2Enabled="true"

By default a forwarded request is only sent over HTTP/2 when the incoming request itself used HTTP/2 (and "Forward Upstream Requests Using HTTP/2" is enabled). Enable this setting to forward a secure (TLS) request to its upstream over HTTP/2 via ALPN even when the incoming client used HTTP/1.1, with automatic fallback to HTTP/1.1 if the upstream does not negotiate HTTP/2.

This is useful when an upstream sends a streaming (Server-Sent Events) response head immediately over HTTP/2 but withholds it over HTTP/1.1 — forwarding over HTTP/2 lets MockServer relay the response head to the client promptly instead of waiting for the whole stream. HTTP/2 only happens over TLS using ALPN (there is no plain-HTTP h2c path, so a non-secure request is unaffected and stays HTTP/1.1). Non-streaming HTTP/2 upstream connections are pooled and reused across requests when connection pooling is enabled.

It applies to both matched forward expectations and the transparent (HTTPS) proxy path used to capture a tool's traffic — so it is the recommended setting when recording a coding-assistant CLI (for example the opencode CLI, whose OpenAI Codex backend withholds its SSE head over HTTP/1.1) through MockServer as an HTTPS proxy, where it otherwise surfaces as a streaming header timeout.

The default (off) is unchanged from previous behaviour.

Type: boolean Default: false

Java Code:

ConfigurationProperties.forwardProxyHttp2Upgrade(boolean enable)

System Property:

-Dmockserver.forwardProxyHttp2Upgrade=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_HTTP2_UPGRADE=...

Property File:

mockserver.forwardProxyHttp2Upgrade=...

Example:

-Dmockserver.forwardProxyHttp2Upgrade="true"

How many times MockServer forwards the same request before it stops a forwarding loop. A forward, a proxyPassMappings entry, or a forwarded WebSocket upgrade whose host and port lead back to MockServer itself would otherwise match the same expectation or mapping again on every hop, opening a new connection each time until MockServer runs out of local ports or open files.

To count the hops, every forward action (including one that forwards a WebSocket upgrade) and proxyPassMappings entry adds a x-mockserver-forwarded-by header to the request it sends, with an identifier for this MockServer (a random value, new each time MockServer starts). When a request arrives that this MockServer has already forwarded this many times, MockServer answers it with 508 Loop Detected instead of forwarding it again, and the body says why and what to check. Each MockServer counts only its own entries, so forwarding to another MockServer, or through a chain of them, still works. A forward that goes back to MockServer on purpose, for example to a different path that another expectation answers, also still works, up to this many times.

The upstream sees the extra header. MockServer leaves it out of recorded expectations, so recordings made by another MockServer still match requests that do not carry it. Set the value to 0 to stop sending the header and turn loop detection off, for example when an upstream rejects headers it does not recognise.

Type: int Default: 10

Java Code:

ConfigurationProperties.forwardLoopMaxHops(int maxHops)

System Property:

-Dmockserver.forwardLoopMaxHops=...

Environment Variable:

MOCKSERVER_FORWARD_LOOP_MAX_HOPS=...

Property File:

mockserver.forwardLoopMaxHops=...

Example:

-Dmockserver.forwardLoopMaxHops="0"

The maximum number of times MockServer retries a forwarded or proxied request to an upstream after a transient failure — a connection error (refused/reset), a timeout, or an upstream response of 502, 503 or 504. Retries reduce flakiness when the real upstream is briefly unavailable.

To avoid executing a request twice, only requests using an idempotent HTTP method (GET, HEAD, OPTIONS, PUT, DELETE, TRACE) are retried; non-idempotent methods (POST, PATCH) are never retried. The default (0) forwards each request exactly once, unchanged from previous behaviour.

A forward whose connection cannot be set up from MockServer's own configuration (for example an outbound client private key that is not valid PEM) is not retried, because it would fail the same way again. Nor is one whose upstream answered with a response MockServer cannot read as HTTP (the client is answered 502 naming why), because the upstream has already received the request. Nor is one that could not reach the upstream proxy set by forwardHttpProxy, forwardHttpsProxy or forwardSocksProxy (its name does not resolve, or it refuses or does not answer the connection): that is a problem with the proxy setting, and MockServer logs a warning naming the proxy the first time it happens.

Type: int Default: 0

Java Code:

ConfigurationProperties.forwardProxyRetryCount(int retryCount)

System Property:

-Dmockserver.forwardProxyRetryCount=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_RETRY_COUNT=...

Property File:

mockserver.forwardProxyRetryCount=...

Example:

-Dmockserver.forwardProxyRetryCount="3"

The base back-off in milliseconds applied between forward/proxy retry attempts. The delay grows linearly with the attempt number (the first retry waits one base delay, the second waits two, and so on) so a flaky upstream is not hammered. Set to 0 to retry immediately. Only relevant when forwardProxyRetryCount is greater than 0.

Type: long Default: 100

Java Code:

ConfigurationProperties.forwardProxyRetryBackoffMillis(long backoffMillis)

System Property:

-Dmockserver.forwardProxyRetryBackoffMillis=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_RETRY_BACKOFF_MILLIS=...

Property File:

mockserver.forwardProxyRetryBackoffMillis=...

Example:

-Dmockserver.forwardProxyRetryBackoffMillis="250"

By default every forwarded or proxied request is attempted against its upstream, however many previous requests failed. Enable this setting to add a per-upstream circuit breaker (keyed by host and port): after forwardProxyCircuitBreakerFailureThreshold consecutive failures to one upstream the breaker trips open and subsequent requests fail fast with a 503 for forwardProxyCircuitBreakerWindowMillis milliseconds, instead of waiting on a dead upstream. After the window a single trial request is allowed through (half-open); a success closes the breaker, a failure re-opens it for another window. A forward that fails because of MockServer's own configuration (for example an outbound key or certificate that is not valid PEM, or a target forwardProxyBlockPrivateNetworks refuses), or because the upstream's response headers are larger than maxHeaderSize, or because the upstream proxy set by forwardHttpProxy, forwardHttpsProxy or forwardSocksProxy could not be reached, counts as neither a success nor a failure: it says nothing about whether the upstream is healthy, so one broken proxy does not open the breaker for every upstream behind it. A proxy that is reached but reports that it could not reach the upstream still counts as a failure of that upstream.

When metrics are enabled the number of currently-open upstreams is exported as the mock_server_upstream_circuit_open Prometheus gauge. The default (off) is unchanged from previous behaviour.

Type: boolean Default: false

Java Code:

ConfigurationProperties.forwardProxyCircuitBreakerEnabled(boolean enable)

System Property:

-Dmockserver.forwardProxyCircuitBreakerEnabled=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_CIRCUIT_BREAKER_ENABLED=...

Property File:

mockserver.forwardProxyCircuitBreakerEnabled=...

Example:

-Dmockserver.forwardProxyCircuitBreakerEnabled="true"

The number of consecutive failures to a single upstream (host and port) that trips the forward/proxy circuit breaker open. Only relevant when forwardProxyCircuitBreakerEnabled is true. Values below 1 are treated as 1.

Type: int Default: 5

Java Code:

ConfigurationProperties.forwardProxyCircuitBreakerFailureThreshold(int failureThreshold)

System Property:

-Dmockserver.forwardProxyCircuitBreakerFailureThreshold=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_CIRCUIT_BREAKER_FAILURE_THRESHOLD=...

Property File:

mockserver.forwardProxyCircuitBreakerFailureThreshold=...

Example:

-Dmockserver.forwardProxyCircuitBreakerFailureThreshold="10"

How long in milliseconds the forward/proxy circuit breaker stays open (failing requests fast with a 503) for an upstream before it transitions to half-open and lets a single trial request through. Only relevant when forwardProxyCircuitBreakerEnabled is true. Values below 1 are treated as 1.

Type: long Default: 30000

Java Code:

ConfigurationProperties.forwardProxyCircuitBreakerWindowMillis(long windowMillis)

System Property:

-Dmockserver.forwardProxyCircuitBreakerWindowMillis=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_CIRCUIT_BREAKER_WINDOW_MILLIS=...

Property File:

mockserver.forwardProxyCircuitBreakerWindowMillis=...

Example:

-Dmockserver.forwardProxyCircuitBreakerWindowMillis="45000"

Use HTTP proxy (i.e. via Host header) for all outbound / forwarded requests

Hosts listed in noProxyHosts are connected to directly, not through this proxy.

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

MockServer does not look up the destination's host name itself: it sends the name to the proxy in the CONNECT request and the proxy resolves it. This works in networks where only the proxy can resolve external names.

Hosts listed in noProxyHosts are connected to directly, not through this proxy.

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

MockServer does not look up the destination's host name itself: it sends the name to the SOCKS proxy, which resolves it. A destination given as an IP address is sent as that address.

Hosts listed in noProxyHosts are connected to directly, not through this proxy.

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.doe

Password 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 realm name MockServer advertises in the Proxy-Authenticate header of a 407 Proxy Authentication Required response, when a client connects to MockServer as a forward/HTTP proxy without the expected credentials (proxyAuthenticationUsername / proxyAuthenticationPassword). This is purely a client-facing label — most HTTP clients display or log it, but it has no effect on whether authentication succeeds. Change it only to customise what a connecting client sees in its proxy-authentication prompt or error.

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.doe

The 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:

• pathPrefix (required) — the incoming path prefix to match, e.g. /api/
• targetUri (required) — the upstream server URI including path, e.g. https://backend:8443/services/
• preserveHost (optional, default false) — if true, the original Host header is preserved instead of being adjusted to match the target

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 hosts that MockServer connects to directly, never through an upstream proxy, and that it does not proxy a request to by guessing.

Upstream proxies: when MockServer sends a request to a host on this list (a forward, a proxied request, a webhook, or a forwarded binary message), it does not go through forwardHttpProxy, forwardHttpsProxy or forwardSocksProxy: MockServer connects to the host itself, as curl and Java do for hosts on no_proxy / http.nonProxyHosts. Unlike curl, a bare * and CIDR ranges (such as 10.0.0.0/8) are not supported and match nothing; list each host, domain or IP address. A forward that names no host and port is checked by its Host header. With forwardProxyBlockPrivateNetworks enabled, a direct connection to a listed host is still checked.

Unmatched requests: when a request that matches no expectation has a Host header on this list, MockServer returns a 404 instead of trying to proxy it to that host.

Each entry is one of:

• a host name, matched exactly (e.g. example.com matches only example.com)
• a domain suffix, written *.internal.corp or .internal.corp, which matches internal.corp and every name under it
• an IP address (e.g. 192.168.1.1 or ::1), which matches only a destination given as that address

Matching ignores case and the port. MockServer does not look names up to match them, so an IP address entry does not match a host name that resolves to it: to connect to a named host directly, list its name.

This setting is fixed at startup: a PUT /mockserver/configuration request cannot change it (a different value is ignored and a warning is logged), so a caller of the control plane cannot route traffic around an upstream proxy you rely on, for example for logging or data-loss checks. Set it with a system property, environment variable, property file or Configuration before the server starts.

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. A CONNECT or SOCKS request is the exception: MockServer tunnels it to itself, and an unmatched request inside that tunnel goes to the tunnel's own target, not to this host.

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"

Enable authentication of data-plane (mocked endpoint) requests. When true, every request to a mocked endpoint must present credentials matching one of the configured data-plane schemes; requests that do not are rejected with 401 Unauthorized. Control-plane requests, health/status/ready probes and CONNECT proxy requests are not affected.

Type: boolean Default: false

Java Code:

ConfigurationProperties.dataPlaneAuthenticationRequired(boolean enable)

System Property:

-Dmockserver.dataPlaneAuthenticationRequired=...

Environment Variable:

MOCKSERVER_DATA_PLANE_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.dataPlaneAuthenticationRequired=...

Example:

-Dmockserver.dataPlaneAuthenticationRequired=true

The username required for data-plane HTTP Basic authentication. Basic is only active when both the username and password are set.

Type: string Default:

Java Code:

ConfigurationProperties.dataPlaneBasicAuthenticationUsername(String dataPlaneBasicAuthenticationUsername)

System Property:

-Dmockserver.dataPlaneBasicAuthenticationUsername=...

Environment Variable:

MOCKSERVER_DATA_PLANE_BASIC_AUTHENTICATION_USERNAME=...

Property File:

mockserver.dataPlaneBasicAuthenticationUsername=...

Example:

-Dmockserver.dataPlaneBasicAuthenticationUsername=john.doe

The password required for data-plane HTTP Basic authentication. Basic is only active when both the username and password are set.

Type: string Default:

Java Code:

ConfigurationProperties.dataPlaneBasicAuthenticationPassword(String dataPlaneBasicAuthenticationPassword)

System Property:

-Dmockserver.dataPlaneBasicAuthenticationPassword=...

Environment Variable:

MOCKSERVER_DATA_PLANE_BASIC_AUTHENTICATION_PASSWORD=...

Property File:

mockserver.dataPlaneBasicAuthenticationPassword=...

Example:

-Dmockserver.dataPlaneBasicAuthenticationPassword="p@ssw0rd"

The realm advertised in the WWW-Authenticate: Basic realm="..." challenge returned on a 401 when Basic is configured.

Type: string Default: MockServer

Java Code:

ConfigurationProperties.dataPlaneBasicAuthenticationRealm(String dataPlaneBasicAuthenticationRealm)

System Property:

-Dmockserver.dataPlaneBasicAuthenticationRealm=...

Environment Variable:

MOCKSERVER_DATA_PLANE_BASIC_AUTHENTICATION_REALM=...

Property File:

mockserver.dataPlaneBasicAuthenticationRealm=...

Example:

-Dmockserver.dataPlaneBasicAuthenticationRealm="My Mocked API"

The token required for data-plane Bearer authentication (Authorization: Bearer <token>). Bearer is active when this value is set.

Type: string Default:

Java Code:

ConfigurationProperties.dataPlaneBearerAuthenticationToken(String dataPlaneBearerAuthenticationToken)

System Property:

-Dmockserver.dataPlaneBearerAuthenticationToken=...

Environment Variable:

MOCKSERVER_DATA_PLANE_BEARER_AUTHENTICATION_TOKEN=...

Property File:

mockserver.dataPlaneBearerAuthenticationToken=...

Example:

-Dmockserver.dataPlaneBearerAuthenticationToken="eyJhbGciOi..."

The name of the header carrying the data-plane API key (e.g. X-API-Key). API-key authentication is only active when both the header name and the value are set.

Type: string Default:

Java Code:

ConfigurationProperties.dataPlaneApiKeyAuthenticationHeader(String dataPlaneApiKeyAuthenticationHeader)

System Property:

-Dmockserver.dataPlaneApiKeyAuthenticationHeader=...

Environment Variable:

MOCKSERVER_DATA_PLANE_API_KEY_AUTHENTICATION_HEADER=...

Property File:

mockserver.dataPlaneApiKeyAuthenticationHeader=...

Example:

-Dmockserver.dataPlaneApiKeyAuthenticationHeader="X-API-Key"

The expected value of the data-plane API-key header. API-key authentication is only active when both the header name and the value are set.

Type: string Default:

Java Code:

ConfigurationProperties.dataPlaneApiKeyAuthenticationValue(String dataPlaneApiKeyAuthenticationValue)

System Property:

-Dmockserver.dataPlaneApiKeyAuthenticationValue=...

Environment Variable:

MOCKSERVER_DATA_PLANE_API_KEY_AUTHENTICATION_VALUE=...

Property File:

mockserver.dataPlaneApiKeyAuthenticationValue=...

Example:

-Dmockserver.dataPlaneApiKeyAuthenticationValue="super-secret-key"

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 (text/event-stream, AWS Bedrock's application/vnd.amazon.eventstream or Ollama's application/x-ndjson), or from a request that asks for a stream (an Accept: text/event-stream header, a JSON body with "stream": true, or a Gemini :streamGenerateContent call), and does not affect non-streaming responses. This applies to every proxied response, from any host, not only to LLM APIs. Ordinary chunked responses without any of these 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"

An OPENAI_RESPONSES mock keeps each response it returns, streamed or not, so a client can continue the conversation with previous_response_id or fetch the response again with GET /v1/responses/{id}, as the real OpenAI Responses API allows. Each kept response includes the tools, instructions and metadata the request sent, so an agent that sends large tool definitions on every turn can make these responses hold a lot of memory.

This setting caps the estimated memory they hold. When the cap is reached, the least recently used responses are discarded first; the most recent one is always kept, so a client can always continue from its latest turn. A discarded response can no longer be chained from or fetched. At most 10,000 responses are kept whatever this value. Lower it on a memory-constrained host; raise it if a long agent run needs to fetch or chain from older turns. Set it to 0 to limit by count only. A request that sends "store": false is never kept. The value can also be changed on a running server with PUT /mockserver/configuration.

Type: long Default: a twentieth of the JVM heap (about 50 MB with -Xmx1g)

Java Code:

ConfigurationProperties.maxOpenAiResponsesSizeInBytes(long bytes)

System Property:

-Dmockserver.maxOpenAiResponsesSizeInBytes=...

Environment Variable:

MOCKSERVER_MAX_OPEN_AI_RESPONSES_SIZE_IN_BYTES=...

Property File:

mockserver.maxOpenAiResponsesSizeInBytes=...

Example:

-Dmockserver.maxOpenAiResponsesSizeInBytes="104857600"

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), exploratory semantic prompt matching, and the plain-language summary that PUT /mockserver/explain?narrate=true adds when llmExplainNarrationEnabled is on. 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):

1. Provider environment conventions — if OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, or OLLAMA_HOST is already set (the same variables each provider SDK reads), MockServer auto-detects a backend. No MockServer configuration needed.
2. A single default backend via the properties below.
3. Named backends via a JSON file (mockserver.llmBackendsConfig) for multiple or advanced setups.

llmProvider selects which backend llmApiKey / llmModel / llmBaseUrl talk to, and accepts one of the Provider enum names: ANTHROPIC, OPENAI, OPENAI_RESPONSES, GEMINI, AZURE_OPENAI, OLLAMA, or BEDROCK. Ollama is the easiest to start with — it needs no key and runs locally. llmModel overrides the provider's default model (for example gpt-4o, claude-sonnet-4-5, or an Ollama-pulled model name); leave it empty to use the provider's own default. llmBaseUrl overrides the provider's default API endpoint — set it to point at a self-hosted or proxied endpoint (for example a local Ollama server, or an OpenAI-compatible gateway); leave it empty to use the provider's standard endpoint. AZURE_OPENAI has no standard endpoint, so it needs llmBaseUrl set to your resource (for example https://my-resource.openai.azure.com); without it no request is sent. The API key is a secret and is redacted (***) anywhere configuration is logged.

Changing the endpoint at runtime clears the key. A PUT /mockserver/configuration request that changes llmBaseUrl, or changes llmProvider while llmBaseUrl is empty (so the provider's own endpoint is used), without also supplying llmApiKey, clears the key MockServer holds and logs a warning, so the key is never sent to the new endpoint. Supply the key again in the same request as the new endpoint to keep using the backend. The ***REDACTED*** value a GET returns does not count as supplying it.

llmBackendsConfig takes the path of a backends JSON file, and the path is shown as you set it — the keys live in the file, which MockServer never returns. If you set the JSON document itself as the value instead, every apiKey in it is masked with ***REDACTED*** when the configuration is read back, and the rest of the document is shown so you can still see which backends are configured. A value that contains JSON but cannot be read as exactly one document is masked in full rather than shown, so nothing hidden inside it can leak. Sending a masked document back is safe, but if you rename or re-order a backend whose key you only ever saw masked, MockServer can no longer tell which key belongs to it — it then applies none of the document and logs a warning, rather than saving a backend with its key silently removed. Supply that backend's real key alongside the rename. The same happens if you change a backend's baseUrl or provider while leaving its key masked, so a key is never sent to an endpoint it was not set for.

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=15000

Example (OpenAI default backend):

-Dmockserver.llmProvider="OPENAI" -Dmockserver.llmApiKey="sk-..."

Request timeout — llmRequestTimeoutMillis caps how long MockServer waits for each outbound call to the configured backend above (drift-detection replay, semantic matching, or explain narration). A backend's own timeoutMillis, when set in llmBackendsConfig, overrides this default for that named backend. Lower it to fail fast against an unreachable or slow backend; raise it for a locally-run model (e.g. Ollama on CPU) that can take longer to respond. Because these features fail closed, a timeout is treated the same as the feature being unconfigured — it never fails the mocked request. Type: long Default: 30000 (30 seconds)

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=...

Explain narration — lets PUT /mockserver/explain?narrate=true (and explainUnmatched) send the explanation, with credentials removed, to the backend above and return a short AI-generated summary beside it. Off by default, so no explanation leaves MockServer even when a backend is configured for other features; turn it on only if you are happy for explanations of your traffic to be sent to that LLM. Type: boolean Default: false

ConfigurationProperties.llmExplainNarrationEnabled(boolean enabled)

-Dmockserver.llmExplainNarrationEnabled=...   MOCKSERVER_LLM_EXPLAIN_NARRATION_ENABLED=...

Approximate usage inference — when true, a mocked LLM completion that does not specify usage has approximate prompt_tokens / completion_tokens filled in (estimated from the request and response text). The counts are an estimate using a simple character/word heuristic, not a provider's exact token billing. Off by default so responses are unchanged unless you opt in; a completion that already specifies usage is never altered. Type: boolean Default: false

ConfigurationProperties.llmInferUsageEnabled(boolean enabled)

-Dmockserver.llmInferUsageEnabled=...   MOCKSERVER_LLM_INFER_USAGE_ENABLED=...

Embedding response size limit — the most numbers one mocked embedding response may hold (number of inputs × dimensions, × the number of Cohere embedding types). Responses using encoding_format: "base64" may hold four times as many. A request asking for more gets a 400 in the provider's own error format. The default keeps a response to about 5.6 MB; raise it to accept bigger batches, for example a LangChain batch of 1,000 inputs at 1,536 dimensions needs at least 384000. Larger responses use more memory. Type: int Default: 262144

ConfigurationProperties.llmEmbeddingMaxResponseValues(int maxValues)

-Dmockserver.llmEmbeddingMaxResponseValues=...   MOCKSERVER_LLM_EMBEDDING_MAX_RESPONSE_VALUES=...

Embedding input length limit — the longest input text, in characters, that an embedding with deterministicFromInput turns into a vector. Building the vector from the text uses memory in proportion to its length (roughly 175 MB for a 1,048,576-character input of all-different words), so a longer input gets a 400 in the provider's own error format. The default is above the largest single input any real embedding provider accepts, so a request the real provider would take is never refused; lower it to limit memory use, or raise it for unusually large test inputs. Random embeddings do not read the text and have no such limit. Before this setting existed, inputs of any length were accepted. Type: int Default: 1048576

ConfigurationProperties.llmEmbeddingMaxInputCharacters(int maxCharacters)

-Dmockserver.llmEmbeddingMaxInputCharacters=...   MOCKSERVER_LLM_EMBEDDING_MAX_INPUT_CHARACTERS=...