Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
507 lines (378 loc) · 9.67 KB

TROUBLESHOOTING.md

File metadata and controls

507 lines (378 loc) · 9.67 KB

Troubleshooting Guide

Common issues and solutions.

Proxy Won't Start

Port Already in Use

Error: listen tcp :8080: bind: address already in use

Solution:

  1. Check what's using the port:

    lsof -i :8080

  2. Kill the existing process:

    kill -9 <PID>

  3. Or use a different port:

    ./markdowninthemiddle --addr :9090

Permission Denied

Error: listen tcp :80: bind: permission denied

Solution:

  • Use a port > 1024 (don't need sudo):

    ./markdowninthemiddle --addr :8080

  • Or run with sudo (not recommended):

    sudo ./markdowninthemiddle --addr :80

Chrome Connection Issues

Chrome Not Connecting (Docker)

Error:

chromedp: failed to connect to Chrome at http://chrome:9222

Solution:

  1. Check Chrome service is running:

    docker compose ps chrome

    Should show Up and healthy

  2. Restart Chrome:

    docker compose restart chrome

  3. Check Chrome logs:

    docker compose logs -f chrome

  4. Verify Chrome port is open:

    curl http://localhost:9222/json/version

Chrome URL Wrong (Local)

Error:

chromedp: failed to connect to Chrome at http://localhost:9222

Solution:

  1. Start Chrome with debugging protocol:

    # macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 &

# Linux
google-chrome --remote-debugging-port=9222 &

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

  2. Or specify the Chrome URL:

    ./markdowninthemiddle --chrome-url http://localhost:9222

  3. Or use helper script:

    ./scripts/start-chrome.sh &
./markdowninthemiddle

HTTPS/TLS Issues

Certificate Generation Failed

Error:

error generating certificate: open ./certs: permission denied

Solution:

  1. Create certs directory:

    mkdir -p certs
chmod 755 certs

  2. Generate certificate manually:

    ./markdowninthemiddle gencert --dir ./certs

  3. Or let Docker handle it:

    cd docker
docker compose up -d

TLS Handshake Error

Error:

http: TLS handshake error from [::1]:12345: tls: first record does not look like a TLS handshake

Solution:

This usually means sending HTTP to an HTTPS port.

  • Use HTTPS with the proxy:

    curl -k -x https://localhost:8080 http://example.com

  • Or disable TLS:

    ./markdowninthemiddle --tls=false

Client Certificate Not Trusted

Error: Browser shows "certificate not trusted" warning

Solution:

For MITM mode, you need to trust the CA certificate:

  1. See HTTPS_SETUP.md for TLS setup
  2. See MITM_SETUP.md for certificate installation

Conversion Not Working

HTML Not Converting to Markdown

Check:

  1. Verify conversion is enabled:

    ./markdowninthemiddle --convert=true

  2. Check response Content-Type:

    curl -x http://localhost:8080 http://example.com -sD - | grep "Content-Type"

    Should be text/html or text/markdown

  3. Check response headers:

    curl -x http://localhost:8080 http://example.com -sD - | grep "X-"

    Look for X-Token-Count (shows it was converted)

JSON Not Converting to Markdown

Check:

  1. Enable JSON conversion:

    ./markdowninthemiddle --convert-json --template-dir ./my-templates

  2. Verify Content-Type is application/json:

    curl -x http://localhost:8080 https://api.example.com/data -sD - | grep "Content-Type"

  3. Check if template matches:

    • Enable debug logging: 
      ./markdowninthemiddle --convert-json --template-dir ./my-templates --log-level debug
    • Look for "template matched" in logs

  4. Verify template naming:

    • Template: api.example.com__users.mustache
    • URL: https://api.example.com/users
    • Scheme is stripped before matching

Negotiate-Only Mode Not Working

Check:

  1. Enable negotiate-only mode:

    ./markdowninthemiddle --negotiate-only

  2. Send Accept header:

    curl -x http://localhost:8080 \
  -H "Accept: text/markdown" \
  http://example.com

    Without header, HTML is returned as-is.

Caching Issues

Cache Not Working

Check:

  1. Enable cache and verify directory:

    ./markdowninthemiddle --cache-dir ./cache

  2. Check cache directory exists and is writable:

    ls -la cache/

  3. Make the same request twice (should be faster second time):

    curl -x http://localhost:8080 http://example.com
curl -x http://localhost:8080 http://example.com  # Should be cached

  4. Check cache files were created:

    ls -la cache/

Cache Control Not Respected

Check:

  1. Verify respect-headers is enabled (default):

    # In config.yml
cache:
  respect_headers: true

  2. Check the API response Cache-Control header:

    curl http://example.com/api -sD - | grep "Cache-Control"

  3. Some APIs use no-store or no-cache (won't be cached)

Token Counting Issues

Token Count Not Appearing

Check:

  1. Verify encoding is correct:

    ./markdowninthemiddle --config ./config.yml
# Check: conversion.tiktoken_encoding in config

  2. Check response has X-Token-Count header:

    curl -x http://localhost:8080 http://example.com -sD - | grep "X-Token-Count"

  3. Invalid encoding will fall back to estimating:

    # Valid: cl100k_base, p50k_base
# Invalid: gibberish → token count will be estimated

Request Filtering Issues

URL Not Being Filtered

Check:

  1. Verify filter pattern:

    ./markdowninthemiddle \
  --allow "^https://api\.example\.com/" \
  --allow "^https://docs\.example\.com/"

  2. Test with a non-matching URL:

    curl -x http://localhost:8080 http://other.com

    Should return 403 Forbidden

  3. Test with matching URL:

    curl -x http://localhost:8080 https://api.example.com/data

    Should work (200 OK)

  4. Check regex pattern is valid:

    • Use regex101.com to test
    • Use Go regex dialect
    • ^ = start, $ = end, \. = literal dot

Docker Issues

Services Won't Start

Check:

  1. Verify docker-compose.yml is valid:

    cd docker
docker compose config

  2. Check logs:

    docker compose logs -f

  3. Look for common errors:

    • Port conflicts: docker ps | grep 8080
    • Image build failures: docker compose build --progress=plain
    • Volume mount issues: docker compose ps and check volumes

Container Exits Immediately

Check:

  1. View detailed logs:

    docker compose logs proxy

  2. Common causes:

    • Config file missing (check volume mounts)
    • Port already in use
    • Cert generation failed

  3. Rebuild and restart:

    docker compose down -v
docker compose build
docker compose up -d

Chrome Service Not Healthy

Check:

  1. View Chrome logs:

    docker compose logs chrome

  2. Test Chrome health manually:

    docker compose exec chrome curl http://localhost:9222/json/version

  3. Increase health check timeout (if needed): Edit docker/docker-compose.yml:

    healthcheck:
  timeout: 15s  # Increase from 10s

Performance Issues

Proxy Slow

Check:

  1. Enable caching:

    ./markdowninthemiddle --cache-dir ./cache

  2. Reduce Chrome pool size if low memory:

    ./markdowninthemiddle --chrome-pool-size 2

  3. Check system resources:

    top -o %MEM  # Memory usage

  4. Use HTTP transport instead of chromedp:

    ./markdowninthemiddle --transport http

Memory Usage High

Check:

  1. Reduce Chrome pool size:

    --chrome-pool-size 2  # Default is 5

  2. Limit response body size:

    --max-body-size 5242880  # 5 MB instead of 10 MB

  3. Disable caching if large:

    # Don't use --cache-dir or --output-dir

Docker Compose on Mac/Windows

Docker Desktop Issues

Problem: docker compose command not found

Solution:

  1. Install Docker Desktop from docker.com
  2. Or use docker-compose (with dash) on older versions: 
    docker-compose up -d  # Old syntax
docker compose up -d  # New syntax

File Permissions Issues

Problem: Volume mounts show permission denied

Solution:

  1. On macOS, Docker Desktop handles permissions automatically
  2. On Windows with WSL2: 
    cd /mnt/c/Users/YourUser/Projects/markdowninthemiddle
docker compose up -d

Still Having Issues?

  1. Check logs:

    ./markdowninthemiddle 2>&1 | tee proxy.log

  2. Enable debug logging:

    ./markdowninthemiddle --log-level debug

  3. Check configuration:

    ./markdowninthemiddle --help
cat config.yml | grep -A5 conversion

  4. Report on GitHub:

    • GitHub Issues
    • Include logs, configuration, error messages
    • Describe what you expected vs what happened

See Also