In MockServer expectations are only held in memory by default. However, it is possible to persist expectations to the local file system to ensure that they survive a restart of MockServer.
To ensure that the persisted expectations are loaded the next time MockServer starts the initializationJsonPath and persistedExpectationsPath should match and the persistExpectations should be set to true as follows:
MOCKSERVER_PERSIST_EXPECTATIONS=true \
MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=mockserverInitialization.json \
MOCKSERVER_INITIALIZATION_JSON_PATH=mockserverInitialization.json \
java -jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080,1081 -logLevel INFOor
java \
-Dmockserver.persistExpectations=true \
-Dmockserver.persistedExpectationsPath=mockserverInitialization.json \
-Dmockserver.initializationJsonPath=mockserverInitialization.json \
-jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080,1081 -logLevel INFOWhen MockServer acts as a proxy, all forwarded requests are automatically recorded as expectations. These recorded expectations can be persisted to a file that is updated each time a new request is forwarded. This enables a record-and-replay workflow where traffic is captured from a real system and then replayed as mock expectations.
MOCKSERVER_PERSIST_RECORDED_EXPECTATIONS=true \
MOCKSERVER_PERSISTED_RECORDED_EXPECTATIONS_PATH=recordedExpectations.json \
MOCKSERVER_INITIALIZATION_JSON_PATH=recordedExpectations.json \
java -jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080,1081 -logLevel INFOor
java \
-Dmockserver.persistRecordedExpectations=true \
-Dmockserver.persistedRecordedExpectationsPath=recordedExpectations.json \
-Dmockserver.initializationJsonPath=recordedExpectations.json \
-jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080,1081 -logLevel INFOThis is separate from the persistExpectations property which persists manually-created expectations. Both can be enabled simultaneously with different file paths.
On Kubernetes, pods are ephemeral — any files written inside the container are lost when the pod restarts. To persist expectations across pod restarts, the MockServer Helm chart supports PersistentVolumeClaims.
The simplest way to enable persistence on Kubernetes is:
helm upgrade --install --namespace mockserver \
--set app.persistence.enabled=true \
mockserver helm/mockserverThis creates a PersistentVolumeClaim and automatically configures MockServer to persist and reload expectations from it. No additional configuration is needed.
For clustered deployments on Kubernetes, use a ReadWriteMany PVC backed by a shared filesystem (e.g. NFS, AWS EFS, or Azure Files). See the Helm chart persistent storage documentation for full details and examples.
By default MockServer reads and writes persisted expectations, recorded proxy traffic, and fixture files on the local filesystem (blobStoreType=filesystem). When several nodes — or several short-lived CI runners — need durable, shared storage of this data without a shared POSIX volume (NFS / EFS / Azure Files), MockServer can store it in a cloud object store instead.
Cloud blob storage is an opt-in module: mockserver-core ships with no cloud SDK on its classpath, so there is no dependency cost unless you use it. Add the module for the backend you want and set blobStoreType to its name — the backend registers itself automatically at startup.
| blobStoreType | Backend | Maven module |
|---|---|---|
| s3 | Amazon S3 (and S3-compatible stores such as MinIO / LocalStack) | org.mock-server:mockserver-blob-s3 |
| gcs | Google Cloud Storage | org.mock-server:mockserver-blob-gcs |
| azure | Azure Blob Storage | org.mock-server:mockserver-blob-azure |
The key required properties per backend are:
An optional blobStoreKeyPrefix applies to all cloud backends so multiple deployments can share one bucket or container without colliding.
The full set of accepted blobStoreType values is filesystem (the default), s3, gcs, azure, and memory. The memory backend keeps blobs in process only — useful for tests or ephemeral runs where you want the persistence code path exercised without writing to disk or a cloud store.
Example (S3) running the Docker image — note that you must use an image with the relevant mockserver-blob-* module (and its cloud SDK) on the classpath:
MOCKSERVER_BLOB_STORE_TYPE=s3 \
MOCKSERVER_BLOB_STORE_BUCKET=my-mockserver-fixtures \
MOCKSERVER_BLOB_STORE_REGION=eu-west-1 \
MOCKSERVER_BLOB_STORE_KEY_PREFIX=ci-shared/ \
MOCKSERVER_PERSIST_EXPECTATIONS=true \
java -jar mockserver-netty-jar-with-dependencies.jar -serverPort 1080 -logLevel INFOWhen a cloud blob store is configured, persisted expectations are restored automatically the next time MockServer starts. Unlike the local filesystem, you do not need to also set initializationJsonPath to match persistedExpectationsPath — that mechanism reads the local disk, which a cloud bucket does not populate, so MockServer reads the persisted document straight from the blob store instead.
The new instance finds the saved document only when all three of the following match the instance that wrote it:
Only the file name is used as the object name — the directory part of persistedExpectationsPath is a local detail and is not included, so two instances can use different local directories (or different containers) and still share the same saved expectations. With the default persistedExpectations.json and a blobStoreKeyPrefix of ci-shared/, the object is stored as ci-shared/persistedExpectations.json. If you point two deployments that must NOT share state at the same bucket, give each its own blobStoreKeyPrefix (or its own file name). If nothing is found, MockServer logs the name it looked for at INFO so you can compare it against what is in the bucket.
Upgrading from an earlier version: the object name has changed. Earlier versions named the object after the full local path of persistedExpectationsPath (something like ci-shared/var/folders/T/persistedExpectations.json); only the file name is used now (ci-shared/persistedExpectations.json). This affects every cloud deployment, whatever your blobStoreKeyPrefix is, so expectations saved by an earlier version are not restored after you upgrade — MockServer starts with no expectations, logs the name it looked for at INFO, and the next change to your expectations saves a new object under the new name, leaving the old one behind in the bucket.
If you need to keep what you already have, list the bucket to find the old name and rename the object once, before starting the new version:
aws s3 ls --recursive s3://my-mockserver-fixtures/ci-shared/
aws s3 mv s3://my-mockserver-fixtures/<old name from the listing> \
s3://my-mockserver-fixtures/ci-shared/persistedExpectations.jsonOtherwise no action is needed — let MockServer start empty and re-create the object the next time your expectations change. The equivalent rename works for Google Cloud Storage (gsutil mv) and Azure Blob Storage (az storage blob copy, then delete the old blob).
The startup read is time-limited by blobStoreRestoreTimeoutSeconds (default 10 seconds), because it happens before MockServer starts listening. If the blob store is unreachable, MockServer logs a warning at that point and starts anyway with no restored expectations, rather than hanging for the cloud SDK's own much longer retry budget and failing your readiness probe. Set it to 0 to skip the restore altogether.
See Configuration Properties for the full property list with defaults, and Centralised Deployment → Cloud Blob Storage for using a blob store across a shared or clustered deployment.
{% include_subpage _includes/clustering.html %} {% include_subpage _includes/initializer_persistence_configuration.html %}