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 duplicate keys exist only the last duplicate key in the file will be processed and all duplicates except the last duplicate will be removed.
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.
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)
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)
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.
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 proxied exchange (FORWARDED_REQUEST log event) is appended to an NDJSON file as it completes — one compact JSON object per line (request + response), flushed immediately after each line. 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).
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"