DIAGNOSTICS & ERROR HANDLING

Troubleshooting & Diagnostics

Resolve common exceptions, interpret secret-safe mismatch reports, and use the built-in `vexfox` command-line toolkit to validate your cassette library.

1. Core Exceptions & How to Fix Them

vexfox.exceptions.RequestMismatchError

Raised during replay mode when an incoming request does not match any recorded interaction in the cassette.

Diagnostic Traceback

9 lines

vexfox.exceptions.RequestMismatchError: No matching recorded interaction found for request: POST https://api.example.com/v1/refunds

Mismatch diagnostics:
  - Interaction #1: JSON body mismatch at key 'amount': expected 1000, got 2500
  - Interaction #2: HTTP method mismatch: expected 'GET', got 'POST'

Recorded interactions in cassette (fixtures/refunds.json):
  * [1] POST https://api.example.com/v1/refunds (matched method/URL, body differed)
  * [2] GET  https://api.example.com/v1/refunds/status

Solution: Check the diff details. If your API call changed intentionally, re-record the interaction using `RecordMode.RECORD` or delete the outdated cassette file in development to allow `RecordMode.ONCE` to regenerate it.

vexfox.exceptions.CassetteNotFoundError

Raised when `RecordMode.REPLAY` is specified and the cassette file does not exist at the given path.

Solution: Ensure you ran tests locally in `RecordMode.ONCE` first to generate the fixture, and confirm the fixture file was committed to Git so your CI runner can locate it.

vexfox.exceptions.NetworkForbiddenInReplayError

Raised when an unexpected network socket is attempted in strict replay mode, guaranteeing that no rogue calls escape to external services.

Solution: Verify that all outbound calls made by the code under test were captured in the cassette.

vexfox.exceptions.InvalidCassetteError

Raised if a cassette JSON file has syntax errors, is empty, or violates Schema v1.

Solution: Run `vexfox validate <cassette-path>` to check for malformed JSON or merge conflict markers.

2. The Command-Line Diagnostics Toolkit

VEXFOX ships with built-in CLI commands to inspect, audit, and validate cassettes without opening Python:

Terminal

11 lines

# 1. Verify system environment, Python version, and HTTPX installation
vexfox doctor

# 2. List all recorded cassettes in a directory with interaction counts
vexfox list ./fixtures

# 3. Inspect a cassette's interactions, HTTP methods, and status codes
vexfox inspect fixtures/refunds.json

# 4. Validate cassette JSON Schema v1 integrity
vexfox validate fixtures/refunds.json

vexfox doctor

Inspects your environment, verifies HTTPX compatibility, and confirms that pytest plugin hooks are loaded.

vexfox validate

Runs JSON Schema v1 checks over your cassette fixtures to catch corrupted files before pushing to CI.

Security & Redaction

Real-World Examples