---
title: "return per-expectation mismatch debug information for a request"
method: PUT
path: "/mockserver/debugMismatch"
tags: ["troubleshooting"]
---

# return per-expectation mismatch debug information for a request

`PUT /mockserver/debugMismatch`

## Request

- Base URL: `http://localhost:1080`
- URL: `http://localhost:1080/mockserver/debugMismatch`
- Auth: none declared

Evaluates the supplied HttpRequest against every active expectation and returns, for each, whether it matched and the per-field differences, plus a closest match. Only HttpRequest definitions are supported (not OpenAPI definitions).

## Request body

- union: request definition
  - HttpRequest: request properties matcher
    - `secure` boolean
    - `keepAlive` boolean
    - `method` union: string value that can be support nottable, optional or a json schema
      - string
      - object
        - `not` boolean
        - `optional` boolean
        - `value` string
        - `schema` Schema (unresolved $ref)
        - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
    - `path` union: string value that can be support nottable, optional or a json schema
      - string
      - object
        - `not` boolean
        - `optional` boolean
        - `value` string
        - `schema` Schema (unresolved $ref)
        - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
    - `pathParameters` union
      - object[]
        - `name` string
        - `values` string[]
      - object
        - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
    - `queryStringParameters` union
      - object[]
        - `name` string
        - `values` string[]
      - object
        - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
    - `body` union: request body matcher
      - object: binary body matcher
        - `not` boolean
        - `type` 'BINARY'
        - `base64Bytes` string
        - `contentType` string
      - object: json body matcher
        - `not` boolean
        - `type` 'JSON'
        - `json` string
        - `contentType` string
        - `matchType` 'STRICT' | 'ONLY_MATCHING_FIELDS'
        - `matchNumbersAsStrings` boolean
      - object: json matching fields body matcher
      - object: json schema body matcher
        - `not` boolean
        - `type` 'JSON_SCHEMA'
        - `jsonSchema` Schema (unresolved $ref)
      - object: JSON path body matcher
        - `not` boolean
        - `type` 'JSON_PATH'
        - `jsonPath` string
      - object: parameter body matcher
        - `not` boolean
        - `type` 'PARAMETERS'
        - `parameters` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
      - object: regex body matcher
        - `not` boolean
        - `type` 'REGEX'
        - `regex` string
      - object: string body matcher
        - `not` boolean
        - `type` 'STRING'
        - `string` string
        - `contentType` string
        - `subString` boolean
      - string: substring body matcher
      - object: xml body matcher
        - `not` boolean
        - `type` 'XML'
        - `xml` string
        - `contentType` string
      - object: xml schema body matcher
        - `not` boolean
        - `type` 'XML_SCHEMA'
        - `xmlSchema` string
      - object: xpath body matcher
        - `not` boolean
        - `type` 'XPATH'
        - `xpath` string
      - object: all-of body matcher — matches only when every one of its component body matchers matches the same request body
        - `not` boolean
        - `optional` boolean
        - `type` 'ALL_OF'
        - `bodyAllOf` Body[], required
      - object: binary body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'BINARY'
        - `base64Bytes` string
        - `contentType` string
      - object: json body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'JSON'
        - `json` string
        - `contentType` string
        - `matchType` 'STRICT' | 'ONLY_MATCHING_FIELDS'
        - `matchNumbersAsStrings` boolean
      - object: json schema body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'JSON_SCHEMA'
        - `jsonSchema` Schema (unresolved $ref)
      - object: JSON path body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'JSON_PATH'
        - `jsonPath` string
      - object: parameter body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'PARAMETERS'
        - `parameters` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
      - object: multipart form-data body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'MULTIPART'
        - `fields` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
        - `filenames` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
        - `partContentTypes` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
      - object: regex body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'REGEX'
        - `regex` string
      - object: string body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'STRING'
        - `string` string
        - `contentType` string
        - `subString` boolean
      - object: xml body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'XML'
        - `xml` string
        - `contentType` string
      - object: xml schema body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'XML_SCHEMA'
        - `xmlSchema` string
      - object: xpath body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'XPATH'
        - `xpath` string
      - object: JSON-RPC body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'JSON_RPC'
        - `method` string
        - `paramsSchema` string
      - object: GraphQL body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'GRAPHQL', required
        - `query` string, required
        - `operationName` string
        - `variablesSchema` string
    - `headers` union
      - object[]
        - `name` string
        - `values` string[]
      - object
        - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
    - `cookies` union
      - object[]
        - `name` string
        - `value` string
      - object
    - `socketAddress` SocketAddress: remote address to send request to, only used for request overrides
      - `host` string
      - `port` integer
      - `scheme` 'HTTP' | 'HTTPS'
    - `protocol` 'HTTP_1_1' | 'HTTP_2' | 'HTTP_3': protocol matcher
    - `jwt` Jwt: JSON Web Token (JWT) request matcher — decodes the token carried in a request header (no signature verification) and matches its claims
      - `header` string: name of the request header carrying the JWT (default 'authorization')
      - `scheme` string: authentication scheme prefix stripped from the header value before decoding (default 'Bearer')
      - `claims` object: claim-value criteria; each value may be an exact string, regex or '!'-negated form
      - `issuer` union: string value that can be support nottable, optional or a json schema
        - string
        - object
          - `not` boolean
          - `optional` boolean
          - `value` string
          - `schema` Schema (unresolved $ref)
          - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
      - `audience` union: string value that can be support nottable, optional or a json schema
        - string
        - object
          - `not` boolean
          - `optional` boolean
          - `value` string
          - `schema` Schema (unresolved $ref)
          - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
      - `algorithm` union: string value that can be support nottable, optional or a json schema
        - string
        - object
          - `not` boolean
          - `optional` boolean
          - `value` string
          - `schema` Schema (unresolved $ref)
          - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
    - `not` boolean
    - `respondBeforeBody` boolean: If true, MockServer responds to a matching request before consuming its body and may close the connection. Required: the matcher must not specify a body matcher, and the action must be RESPONSE or ERROR.
  - OpenAPIDefinition: open api or swagger request matcher
    - `specUrlOrPayload` string
    - `operationId` string
    - `not` boolean
    - `contextPathPrefix` string
  - ConditionalRequestDefinition: conditional (if-then-else) request matcher: if the 'if' guard matches the request then the 'then' branch is required, otherwise the 'else' branch is required (when 'else' is omitted the expectation matches whenever the guard is false)
    - `not` boolean
    - `if` RequestDefinition, required (recursive)
    - `then` RequestDefinition (recursive)
    - `else` RequestDefinition (recursive)

## Response `200`

mismatch debug information returned

- DebugMismatchResult: every active expectation, in evaluation order, compared field by field with the supplied request, and the one that came closest (PUT /mockserver/debugMismatch)
  - `correlationId` string: a new id for this call, not the id of a recorded request
  - `timestamp` string, date-time: when this result was computed
  - `totalExpectations` integer: how many expectations are stored
  - `evaluatedExpectations` integer: how many expectations were evaluated, at most maxExpectationsEvaluated
  - `truncated` boolean: present and true when there were more expectations than maxExpectationsEvaluated
  - `maxExpectationsEvaluated` integer: the evaluation limit (100); present only when truncated is true
  - `closestMatch` ClosestMatch: the non-matching expectation with the fewest differing fields; absent when every one matches
    - `expectationId` string
    - `matchedFields` integer
    - `totalFields` integer
  - `results` ExplainedExpectation[]: one entry per evaluated expectation, in evaluation order; an expectation that is used up is left out
    - `expectationId` string
    - `expectationMethod` string
    - `expectationPath` string
    - `position` integer: the expectation's 1-based position in the order MockServer evaluates expectations
    - `priority` integer
    - `reason` 'NAMESPACE' | 'INACTIVE' | 'FIELDS_DIFFER' | 'NOT_OPERATOR' | 'CONVERSATION' | 'SCENARIO_STATE' | 'PERCENTAGE' | 'LOWER_PRIORITY'
    - `explanation` string: why the expectation was passed over, in plain language
    - `matches` boolean: whether the request matches the expectation's request matcher; absent when an earlier gate decided
    - `matchedFieldCount` integer
    - `totalFieldCount` integer
    - `differingFieldCount` integer
    - `differences` object: for each differing field, the differences found
    - `remediation` object: for each differing field, a hint on how to change the expectation
    - `suggestedFix` SuggestedFix: an RFC 6902 JSON patch of an expectation, as PUT /mockserver/retrieve?type=active_expectations returns it, that would make it match the request (PUT /mockserver/explainUnmatched with suggestFixes); nothing is applied
      - `patch` object[]: the patch operations, each under /httpRequest; empty when no field could be patched
        - `op` 'add' | 'remove' | 'replace' | 'test'
        - `path` string: a JSON pointer into the expectation
        - `value` unknown
      - `patchedFields` string[]: the differing fields the patch changes
      - `unpatchedFields` object[]: the differing fields the patch leaves alone, each with the reason
        - `field` string
        - `reason` string
      - `matchesAfterPatch` boolean: whether the patched expectation matches the request; false when the patch is empty

## Other responses

- `400`: an OpenAPI definition was supplied instead of an HttpRequest, or the request could not be processed

---

[API](https://skmtc.dev/mock-server/apis/mockserver-api.md) · [All operations](https://skmtc.dev/mock-server/apis/mockserver-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mock-server/apis/mockserver-api/revisions/9239b693996e?raw)