Logs & State

MockServer maintains internal state that you can inspect, clear, and persist:

Recorded requests — every request received since MockServer last started or was reset
Active expectations — all currently registered expectations
Recorded expectations — expectations captured from proxied traffic
Logs — all internal log events

Log levels

The log level controls how much detail MockServer records. Set it using the mockserver.logLevel property or MOCKSERVER_LOG_LEVEL environment variable.

Level	What it includes
`TRACE`	Low-level details, full request/response content, and verbose matcher internals. Generates a large volume of output.
`DEBUG`	All matcher results including which specific matchers failed (e.g. a particular header value mismatch). Useful when debugging why a request is not matching.
`INFO`	All interactions: expectations created, requests matched, expectations cleared, verifications run. (Default)
`WARN`	Exceptions and errors only.
`ERROR`	Critical errors only.
`OFF`	No logging.

Change the log level at runtime without restarting MockServer:

ConfigurationProperties.logLevel("DEBUG");

-Dmockserver.logLevel=DEBUG

MOCKSERVER_LOG_LEVEL=DEBUG

java -jar mockserver.jar -serverPort 1080 -logLevel DEBUG

Use DEBUG when debugging why an expectation is not matching. Use INFO for normal operation. Use OFF only if logging overhead is a concern and you have no need to inspect state.

Retrieving recorded requests

Retrieve all requests MockServer has received since it last started or was reset:

HttpRequest[] requests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
    );

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS"

Filter by request properties to retrieve only matching requests:

HttpRequest[] requests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/api/users")
            .withMethod("POST")
    );

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS" \
  -d '{"path": "/api/users", "method": "POST"}'

Retrieving active expectations

Retrieve all currently registered expectations:

Expectation[] expectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
    );

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS"

Filter by request matcher to retrieve only expectations that match certain request properties:

Expectation[] expectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS" \
  -d '{"path": "/some/path", "method": "POST"}'

Retrieving recorded logs

Retrieve the log messages MockServer has recorded:

String logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessages(
        request()
    );

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS"

Filter logs to only those related to a specific path:

String logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessages(
        request()
            .withPath("/api/users")
    );

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS" \
  -d '{"path": "/api/users"}'

Clearing state

Clear state selectively using the type parameter. This is useful between tests to remove expectations or logs without fully resetting MockServer.

Type	What is cleared
`all`	Recorded requests, active expectations, recorded expectations, and logs
`log`	Recorded requests and log entries only
`expectations`	Active and recorded expectations only

Clear all state matching a request path

new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/api/users")
);

curl -X PUT "http://localhost:1080/mockserver/clear" \
  -d '{"path": "/api/users"}'

Clear only logs for a specific path

new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/api/users"),
    ClearType.LOG
);

curl -X PUT "http://localhost:1080/mockserver/clear?type=log" \
  -d '{"path": "/api/users"}'

Clear only expectations for a specific path

new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/api/users"),
    ClearType.EXPECTATIONS
);

curl -X PUT "http://localhost:1080/mockserver/clear?type=expectations" \
  -d '{"path": "/api/users"}'

When logLevel is set to DEBUG, clear operations mark log entries as deleted rather than removing them. This keeps the UI’s log history intact so you can still debug interactions that occurred before the clear.

Resetting all state

Reset removes all recorded requests, all active expectations, all recorded expectations, and all logs:

new MockServerClient("localhost", 1080).reset();

curl -X PUT "http://localhost:1080/mockserver/reset"

Reset is irreversible. All state is discarded immediately. If you need to recover expectations, persist them first (see below).

Persisting expectations

By default, expectations exist only in memory and are lost when MockServer restarts. Enable persistence to write expectations to a JSON file that MockServer reloads on startup.

Enable persistence

Set the persistence properties

MOCKSERVER_PERSIST_EXPECTATIONS=true
MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=mockserverExpectations.json
MOCKSERVER_INITIALIZATION_JSON_PATH=mockserverExpectations.json

java \
  -Dmockserver.persistExpectations=true \
  -Dmockserver.persistedExpectationsPath=mockserverExpectations.json \
  -Dmockserver.initializationJsonPath=mockserverExpectations.json \
  -jar mockserver.jar -serverPort 1080

mockserver.persistExpectations=true
mockserver.persistedExpectationsPath=mockserverExpectations.json
mockserver.initializationJsonPath=mockserverExpectations.json

Confirm the file is reused on restart

Set persistedExpectationsPath and initializationJsonPath to the same file so MockServer both writes to and reads from the same location. On each restart, MockServer loads expectations from this file before accepting requests.

MockServer updates the persistence file automatically whenever expectations are added, cleared, or expire. To watch the initialization file for external changes and reload expectations without restarting:

mockserver.watchInitializationJson=true

Get Started

Mocking

Proxying

Configuration

Debugging

Log levels

Retrieving recorded requests

Retrieving active expectations

Retrieving recorded logs

Clearing state

Clear all state matching a request path

Clear only logs for a specific path

Clear only expectations for a specific path

Resetting all state

Persisting expectations

Enable persistence

​Log levels

​Retrieving recorded requests

​Retrieving active expectations

​Retrieving recorded logs

​Clearing state

​Clear all state matching a request path

​Clear only logs for a specific path

​Clear only expectations for a specific path

​Resetting all state

​Persisting expectations

​Enable persistence

Log levels

Retrieving recorded requests

Retrieving active expectations

Retrieving recorded logs

Clearing state

Clear all state matching a request path

Clear only logs for a specific path

Clear only expectations for a specific path

Resetting all state

Persisting expectations

Enable persistence