Skip to content

docs: add troubleshooting guide#1853

Open
Suraj-H675 wants to merge 1 commit into
httpie:masterfrom
Suraj-H675:docs/add-troubleshooting-guide
Open

docs: add troubleshooting guide#1853
Suraj-H675 wants to merge 1 commit into
httpie:masterfrom
Suraj-H675:docs/add-troubleshooting-guide

Conversation

@Suraj-H675
Copy link
Copy Markdown

What problem does this solve?

HTTPie has 38k stars and millions of users but no troubleshooting guide. Users hit SSL errors, proxy issues, connection timeouts, and JSON parse errors regularly β€” there's no central place that explains what went wrong and how to fix it.

What was changed and why?

Added docs/troubleshooting.md with six sections:

  • Collecting Debug Information β€” how to use --debug for useful bug reports
  • Exit Status Codes β€” all HTTPie exit codes (0, 1, 2, 3, 4, 5, 6, 7, 130) with meanings
  • Connection Problems β€” connection refused/timeout, SSL errors (cert verify failed, version mismatch), proxy errors (auth failures, tunnel errors)
  • Request Errors β€” JSON parse errors with shell quoting fixes, invalid HTTP status codes, Content-Encoding gzip download errors (refs Fix incomplete download error when Content-Encoding gzip is presentΒ #1843, Fix false 'Incomplete download' error when Content-Encoding is setΒ #1707)
  • Authentication Errors β€” missing env vars, SSL client cert auth
  • Shell and Platform Issues β€” httpie vs http on macOS, Windows path expansion, Python version requirements

Exit status codes sourced from httpie/status.py, SSL options from httpie/ssl_.py, error messages from actual code paths in urllib3/requests stack.

How was this tested?

  • Diff verified: only docs/troubleshooting.md added, +257 lines
  • Exit status codes sourced from ExitStatus enum in httpie/status.py
  • SSL version options verified against httpie/ssl_.py's SSL_VERSION_ARG_MAPPING
  • Markdown formatting follows existing httpie docs style

Checklist


This contribution was created with AI assistance following structured guidelines, with human review and approval at each step.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants