How to Debug Proxy Issues Using Charles, Fiddler, and mitmproxy

By /

How to Debug Proxy Issues Using Charles, Fiddler, and mitmproxy

When standard troubleshooting steps fail to resolve a proxy issue, traffic inspection tools become essential. Charles Proxy, Fiddler, and mitmproxy allow you to capture, inspect, and modify HTTP/HTTPS traffic in real time. By watching exactly what your client sends and what the proxy or server returns, you can pinpoint misconfigured headers, authentication failures, redirect loops, and dozens of other issues that are invisible without traffic analysis.

This guide covers how to set up and use each tool specifically for debugging proxy-related problems.

When to Use Traffic Inspection Tools

Reach for a traffic inspection tool when:

  • Your proxy returns errors but the error message is vague
  • Requests succeed in cURL but fail in your application
  • You suspect headers are being modified or stripped by the proxy
  • Authentication is failing and you need to see the exact credentials being sent
  • You need to verify that traffic is actually routing through the proxy
  • You want to compare requests with and without the proxy to identify differences

Charles Proxy

Charles Proxy is a graphical HTTP debugging tool available on Windows, macOS, and Linux. It acts as a local proxy that captures all HTTP and HTTPS traffic passing through it.

Setup for Proxy Debugging

The key concept is chaining: you point your application at Charles, and Charles forwards traffic to your actual proxy. This lets you inspect traffic before and after it passes through your proxy.

  1. Install Charles and launch it
  2. Configure external proxy chaining:
  • Go to Proxy > External Proxy Settings
  • Check “Use external proxy servers”
  • Enter your actual proxy’s host, port, and credentials
  • Check the protocols (HTTP and HTTPS) your proxy uses
  1. Configure your application to use Charles as its proxy (typically localhost:8888)
  2. Enable SSL proxying to decrypt HTTPS traffic:
  • Go to Proxy > SSL Proxying Settings
  • Add . to enable SSL proxying for all hosts
  • Install Charles’s root certificate on your system (Help > SSL Proxying > Install Certificate)

Debugging with Charles

Inspecting request headers:

Click any request in the sequence view. The Request tab shows exactly what your application sent, including:

  • The proxy CONNECT request (for HTTPS)
  • All HTTP headers
  • The Proxy-Authorization header (if using authenticated proxies)
  • The request body

Identifying proxy authentication issues:

Filter the sequence view for 407 responses. Click the response to see:

  • The Proxy-Authenticate header showing the required auth scheme
  • The Proxy-Authorization header your client sent (or lack thereof)
  • Any error messages in the response body

Comparing proxied vs direct requests:

  1. Capture a request through the proxy
  2. Disable the external proxy in Charles
  3. Make the same request directly
  4. Use the Compare function (right-click > Compare) to see the differences

Throttling simulation:

Charles can simulate slow connections to test how your application handles proxy latency:

  • Go to Proxy > Throttle Settings
  • Enable Throttling and select a bandwidth preset

Charles Limitations

  • Commercial software (requires license after trial)
  • May struggle with very high request volumes
  • SSL proxying requires certificate installation on the client system

Fiddler

Fiddler is a free web debugging proxy available for Windows (Fiddler Classic), macOS, and Linux (Fiddler Everywhere). Fiddler Everywhere is the modern, cross-platform version.

Setup for Proxy Debugging

  1. Install Fiddler and launch it
  2. Configure gateway proxy:
  • Go to Settings > Gateway
  • Select “Use specified proxy”
  • Enter your proxy’s host:port
  • For authenticated proxies, use the format user:pass@host:port
  1. Enable HTTPS decryption:
  • Go to Settings > HTTPS
  • Check “Capture HTTPS traffic”
  • Install and trust the Fiddler root certificate
  1. Configure your application to use Fiddler as its proxy (default: localhost:8866 for Fiddler Everywhere, localhost:8888 for Classic)

Debugging with Fiddler

Using the Inspectors panel:

Select a captured request to see:

  • Headers inspector: All request and response headers
  • Raw inspector: The complete raw HTTP message
  • JSON/XML inspector: Parsed response body
  • Timing inspector: Detailed timing breakdown showing where latency occurs

Filtering for proxy issues:

Use the filter bar to focus on problem requests:

  • Filter by response code: status:407 or status:502
  • Filter by host: host:proxy.example.com
  • Filter by process: useful when multiple applications share the proxy

Using AutoResponder for testing:

Fiddler’s AutoResponder lets you simulate proxy responses without connecting to the actual proxy:

  1. Go to the AutoResponder tab
  2. Add a rule matching your proxy endpoint
  3. Configure it to return a specific response (e.g., 407 to test authentication handling)

Composing custom requests:

Use the Composer tab to manually craft requests through the proxy, modifying headers and body to test different configurations.

Fiddler Limitations

  • Fiddler Everywhere requires an account and has paid tiers for advanced features
  • SOCKS proxy support is limited in Fiddler Classic
  • High-volume capture can consume significant memory

mitmproxy

mitmproxy is an open-source, command-line HTTP proxy with powerful scripting capabilities. It runs on Windows, macOS, and Linux and is ideal for automated debugging workflows.

Setup for Proxy Debugging

# Install mitmproxy
pip install mitmproxy

# Start mitmproxy with upstream proxy (chaining)
mitmproxy --mode upstream:http://user:pass@proxy.example.com:8080

# Or use mitmdump for non-interactive capture
mitmdump --mode upstream:http://user:pass@proxy.example.com:8080

For HTTPS inspection, install the mitmproxy CA certificate:

# Start mitmproxy, then visit http://mitm.it through it to download the cert
# Or manually install from ~/.mitmproxy/mitmproxy-ca-cert.pem

Configure your application to use mitmproxy (default: localhost:8080).

Debugging with mitmproxy

Interactive mode (mitmproxy):

The terminal UI shows all captured flows. Navigate with arrow keys, press Enter to inspect details:

  • q – Quit current view
  • f – Set a filter expression
  • e – Edit the request or response
  • r – Replay a request
  • z – Clear all flows

Filtering proxy-related traffic:

# Filter for 407 responses
~c 407

# Filter for specific proxy errors
~c 502 | ~c 503 | ~c 504

# Filter for requests containing proxy headers
~hq Proxy-Authorization

Scripting for automated debugging:

Create a Python script to log proxy-related issues:

# debug_proxy.py
from mitmproxy import http

def response(flow: http.HTTPFlow):
    if flow.response.status_code in [407, 502, 503, 504]:
        print(f"PROXY ERROR: {flow.response.status_code}")
        print(f"  URL: {flow.request.pretty_url}")
        print(f"  Request headers: {dict(flow.request.headers)}")
        print(f"  Response headers: {dict(flow.response.headers)}")
        print(f"  Response body: {flow.response.text[:500]}")
        print()
# Run with the script
mitmdump --mode upstream:http://proxy:8080 -s debug_proxy.py

Comparing proxy behavior:

# compare_proxy.py - Log differences between proxied and direct requests
from mitmproxy import http

def request(flow: http.HTTPFlow):
    # Log all outgoing headers for analysis
    print(f"REQUEST: {flow.request.method} {flow.request.pretty_url}")
    for k, v in flow.request.headers.items():
        print(f"  {k}: {v}")

Modifying requests in transit:

# fix_headers.py - Add missing headers that the proxy requires
from mitmproxy import http

def request(flow: http.HTTPFlow):
    # Add Proxy-Authorization if missing
    if "Proxy-Authorization" not in flow.request.headers:
        import base64
        creds = base64.b64encode(b"user:pass").decode()
        flow.request.headers["Proxy-Authorization"] = f"Basic {creds}"

mitmproxy Web Interface

mitmproxy also offers a web-based UI:

mitmweb --mode upstream:http://proxy:8080

This opens a browser-based interface at http://localhost:8081 that provides a visual flow list similar to Charles and Fiddler.

mitmproxy Advantages

  • Free and open source
  • Scriptable with Python for automated debugging
  • Handles high request volumes efficiently
  • Can be deployed on remote servers for server-side proxy debugging

Choosing the Right Tool

FeatureCharlesFiddlermitmproxy
PlatformWin/Mac/LinuxWin/Mac/LinuxWin/Mac/Linux
LicenseCommercialFree/Paid tiersOpen source
UIGUIGUICLI/Web
ScriptingLimitedJScript.NETPython
Upstream proxyYesYesYes
SOCKS supportYesLimitedYes
PerformanceModerateModerateHigh
Best forVisual debuggingWindows/.NETAutomation/scripting

Practical Debugging Workflow

  1. Reproduce the issue with your normal proxy setup and note the exact error
  2. Set up the debugging proxy (Charles, Fiddler, or mitmproxy) between your client and the proxy
  3. Capture the failing request and inspect:
  • Are the proxy credentials being sent correctly?
  • Is the CONNECT request succeeding?
  • What status code does the proxy return?
  • Are any headers being modified or stripped?
  1. Compare with a working request to identify the difference
  2. Test modifications by editing headers or credentials in the debugging tool
  3. Apply the fix to your application configuration

For a comprehensive post-fix validation process, use the proxy testing checklist to confirm everything works correctly. When working with mobile proxies, these debugging tools are particularly valuable for verifying that mobile carrier headers are being passed through correctly.

Conclusion

Traffic inspection tools transform proxy debugging from guesswork into precise diagnosis. Charles Proxy offers the best visual debugging experience, Fiddler excels in Windows environments, and mitmproxy provides unmatched automation capabilities through Python scripting. Set up the tool between your client and your proxy, capture the failing traffic, and inspect the raw HTTP messages. The answer to your proxy problem is almost always visible in the traffic capture.

Related Reading

Scroll to Top