Debug Mode

Rift provides a debug mode that returns stub matching information instead of executing the actual response. This is useful for diagnosing why requests match (or don’t match) specific stubs.

Note: This is a Rift extension. Mountebank does not provide this feature.

Overview

When you send a request with the X-Rift-Debug: true header, Rift will:

  1. Find the matching stub (if any)
  2. Return detailed match information as JSON
  3. Not execute the actual response

This allows you to see exactly which stub would handle a request without side effects.

Usage

Add the X-Rift-Debug header to any request:

curl -H "X-Rift-Debug: true" http://localhost:4545/api/users

Header Values

The debug mode accepts:

  • X-Rift-Debug: true (case-insensitive)
  • X-Rift-Debug: 1
  • x-rift-debug: true (lowercase)

Response Format

When a Stub Matches 

{
  "debug": true,
  "request": {
    "method": "GET",
    "path": "/api/users",
    "query": "page=1",
    "headers": {
      "Accept": "*/*",
      "Host": "localhost:4545"
    },
    "body": null
  },
  "imposter": {
    "port": 4545,
    "name": "User Service",
    "protocol": "http",
    "stubCount": 3
  },
  "matchResult": {
    "matched": true,
    "stubIndex": 0,
    "stubId": "get-users",
    "predicates": [
      {"equals": {"method": "GET", "path": "/api/users"}}
    ],
    "responsePreview": {
      "responseType": "is",
      "statusCode": 200,
      "headers": {"Content-Type": "application/json"},
      "bodyPreview": "[{\"id\": 1, \"name\": \"Alice\"}]"
    }
  }
}

When No Stub Matches

When no stub predicates match the request, the response includes all configured stubs for inspection:

{
  "debug": true,
  "request": {
    "method": "GET",
    "path": "/unknown/path",
    "headers": {...}
  },
  "imposter": {
    "port": 4545,
    "name": "User Service",
    "protocol": "http",
    "stubCount": 3
  },
  "matchResult": {
    "matched": false,
    "reason": "No stub predicates matched the request",
    "allStubs": [
      {
        "index": 0,
        "id": "get-users",
        "predicates": [{"equals": {"method": "GET", "path": "/api/users"}}],
        "responseCount": 1
      },
      {
        "index": 1,
        "id": "create-user",
        "predicates": [{"equals": {"method": "POST", "path": "/api/users"}}],
        "responseCount": 1
      },
      {
        "index": 2,
        "predicates": [{"startsWith": {"path": "/api"}}],
        "responseCount": 1
      }
    ]
  }
}

Response Fields

Top Level

Field Type Description
debug boolean Always true for debug responses
request object Information about the incoming request
imposter object Information about the imposter
matchResult object Stub matching result

Request Object

Field Type Description
method string HTTP method (GET, POST, etc.)
path string Request path
query string Query string (if present)
headers object Request headers (excluding X-Rift-Debug)
body string Request body (if present)

Imposter Object

Field Type Description
port number Port the imposter listens on
name string Imposter name (if configured)
protocol string http or https
stubCount number Number of configured stubs

Match Result Object (When Matched)

Field Type Description
matched boolean true if a stub matched
stubIndex number Index of the matching stub (0-based)
stubId string Stub ID (if configured)
predicates array The matching stub’s predicates
responsePreview object Preview of the response

Match Result Object (When Not Matched)

Field Type Description
matched boolean false when no stub matches
reason string Explanation of why no stub matched
allStubs array List of all configured stubs

Response Preview Object

Field Type Description
responseType string is, proxy, inject, fault, or _rift
statusCode number HTTP status code (for is responses)
headers object Response headers (for is responses)
bodyPreview string First 500 characters of the body

Examples

Debugging a Matching Request 

# Create an imposter with multiple stubs
curl -X POST http://localhost:2525/imposters -d '{
  "port": 4545,
  "protocol": "http",
  "stubs": [
    {
      "id": "get-user-123",
      "predicates": [{"equals": {"path": "/users/123"}}],
      "responses": [{"is": {"statusCode": 200, "body": "{\"id\": 123}"}}]
    },
    {
      "id": "list-users",
      "predicates": [{"startsWith": {"path": "/users"}}],
      "responses": [{"is": {"statusCode": 200, "body": "[]"}}]
    }
  ]
}'

# Debug which stub matches
curl -H "X-Rift-Debug: true" http://localhost:4545/users/123

Response shows stub index 0 (get-user-123) matches.

Debugging a Non-Matching Request 

curl -H "X-Rift-Debug: true" http://localhost:4545/orders/456

Response shows no match and lists all stubs so you can see why none matched.

Debugging Why Wrong Stub Matches 

# If /users/123 is matching the wrong stub, use debug mode to see:
curl -H "X-Rift-Debug: true" http://localhost:4545/users/123

# Response shows which stub actually matched and its predicates
# Common issues:
# - Catch-all stub before specific stub
# - startsWith matching before equals
# - Wrong method in predicate

Use Cases

  1. Diagnosing Match Failures
    • See why a request doesn’t match any stub
    • View all stubs to identify missing or incorrect predicates
  2. Understanding First-Match-Wins
    • See which stub wins when multiple could match
    • Identify stub ordering issues
  3. Verifying Stub Configuration
    • Confirm the right response would be returned
    • Check response preview without executing
  4. CI/CD Integration
    • Programmatically verify stub routing
    • Validate imposter configuration

Response Headers

Debug responses include:

  • Content-Type: application/json
  • X-Rift-Debug-Response: true - Indicates this is a debug response

Mountebank Compatibility

Feature Mountebank Rift
Debug mode No Yes
X-Rift-Debug header Ignored Activates debug mode
Match information N/A Full details
All stubs listing N/A When no match

The X-Rift-Debug header is a Rift extension. If sent to Mountebank, it will be ignored and the request will be processed normally.