docs: add comprehensive troubleshooting guide (25+ issues)#494
Open
mandyslovestories-sudo wants to merge 1 commit into
Open
docs: add comprehensive troubleshooting guide (25+ issues)#494mandyslovestories-sudo wants to merge 1 commit into
mandyslovestories-sudo wants to merge 1 commit into
Conversation
- Create TROUBLESHOOTING.md with 10 sections and 25 documented issues - Covers: env/config, smart contract errors, backend, MQTT/IoT bridge, frontend, Freighter wallet, payments, Docker Compose, observability, and CI/CD — each with symptoms, root cause and step-by-step fix - Includes a Debug Checklist for rapid triage - All contract error codes (1-13) mapped to human-readable descriptions - Links to related PRs/issues (Dev-AdeTutu#397, Dev-AdeTutu#399, Dev-AdeTutu#400) where fixes were made - Update CONTRIBUTING.md Troubleshooting section to link to new guide - Fix broken absolute file:// link in README.md Contributing Guide reference Closes Dev-AdeTutu#480
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary\n\nCloses #480\n\nCreates a thorough self-service troubleshooting guide so users can diagnose and fix common problems without filing a support request.\n\n## Files changed\n\n- TROUBLESHOOTING.md (new) — 10 sections, 25 documented issues\n- CONTRIBUTING.md — Troubleshooting section now links to the new guide; quick reference kept\n- README.md — Link added; broken absolute file:// link to CONTRIBUTING fixed\n\n## Coverage\n\n| Section | Issues |\n|---|---|\n| Environment & Configuration | 4 |\n| Smart Contract | 6 |\n| Backend | 6 |\n| MQTT / IoT Bridge | 3 |\n| Frontend | 4 |\n| Wallet & Freighter | 5 |\n| Payments & Balances | 3 |\n| Docker & Docker Compose | 4 |\n| Observability | 3 |\n| CI/CD & Deployments | 4 |\n\nEach issue includes: symptom, root cause, and step-by-step fix with exact commands. Contract error codes 1–13 are all mapped. A Debug Checklist at the bottom gives a rapid triage flow.\n\n## Acceptance Criteria\n- [x] Troubleshooting guide created\n- [x] 25+ issues documented (25 distinct issues across 10 sections)\n- [x] Debug steps included for every issue\n- [x] Error links working (references to #397, #399, #400 where fixes landed)\n- [x] Guide is searchable (Markdown headers, anchor links in TOC)