B9: add Troubleshooting section to README#4
Merged
Conversation
Covers the failure modes users actually hit, based on the error handling already in substack_link_checker.py: 403s (cookie / rotated cookie / concurrency), missing year-specific sitemap (fall back to fetch_archive_urls.py), DNS / Timeout for rate-limited targets (--skip-domains), SSL errors against old TLS hosts (--broken-domains), soft-404 false positives, empty CSV report, and --only-new not skipping. Each entry is one-line problem + one-line cause + copy-pasteable fix. Screenshot is intentionally not included: producing a real one would require running against a real Substack with a real cookie, and the existing "Example Output" code block already conveys the same information in maintainable text form. Easy to add a real screenshot later. Docs only — no code changes, no test changes.
4 tasks
5 tasks
jcddc83
added a commit
that referenced
this pull request
May 19, 2026
) * Prepare v1.1.0: bump version + fix stale troubleshooting invocations Version bump: - pyproject.toml: 1.0.0 -> 1.1.0 - src/substack_link_checker/__init__.py: __version__ -> 1.1.0 - CHANGELOG.md: rename [Unreleased] -> [1.1.0] - 2026-05-19, add a fresh empty [Unreleased] section above it Troubleshooting fix: - README.md Troubleshooting section's code blocks still used the pre-refactor `python substack_link_checker.py ...` / `python fetch_archive_urls.py ...` form because PR #4 was based on the audit branch before B3's CLI rewrite landed. Updated to the current `substack-link-checker check ...` and `substack-link-checker fetch-archive ...` invocations so a reader following the troubleshooting steps doesn't hit "command not found" on the main entry point. Once this lands, push tag v1.1.0 to trigger the release workflow (which builds the wheel/sdist and attaches them to the GitHub Release). * Fix CI smoke test (root-level substack_link_checker.py is gone) The CI test job has been running `python substack_link_checker.py --help` as a post-install smoke test since PR #1. B3 (PR #3) deleted that file when refactoring the codebase into the src-layout package, but didn't update this step. CI has been failing on every PR since B3 merged. Replace with two invocations against the installed console script: - `substack-link-checker --help` (top-level dispatcher) - `substack-link-checker check --help` (check subcommand) This is also why the actions/checkout Dependabot PR (#7) was reported as failing — same root cause, not the action bump itself. --------- Co-authored-by: Claude <noreply@anthropic.com>
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
2 participants
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
Adds a Troubleshooting section to
README.mdcovering the failure modes users actually hit, based on the error handling already insubstack_link_checker.py:HTTP 403 Forbidden— cookie / rotated cookie / lower concurrencySitemap returns no posts for --year YYYY— fall back tofetch_archive_urls.pyDNS Failure/Timeoutfor links that work in browser —--skip-domainsConnection Error: ...ssl:default— old TLS on target →--broken-domainsSoft 404results that look fine — title-matcher false positives, eyeball them--only-newnot skipping anything —--history-filenot set / not matching previous runEach entry: one-line problem + one-line cause + copy-pasteable fix.
Why no screenshot
The plan called for a "screenshot of CSV report" but producing a real one would require running against a real Substack with a real cookie, which I can't do from the sandbox. The existing "Example Output" code block already conveys the same information in maintainable text form (screenshots of terminal output go stale quickly). Happy to add a real one later if you want — drop a PNG in the repo and I'll wire it in.
Stacked on #1
Based on
claude/audit-github-repo-EWQDn(PR #1). This README uses the pre-B3 invocations (python substack_link_checker.py …) to stay consistent with the rest of the README on this branch.python substack_link_checker.py …→substack-link-checker check …throughout README. When PR #3 lands, the troubleshooting block here will need its commands updated the same way. Cleanest merge order:Either works; both end at the same place. Happy to do the rebase myself once you've picked an order.
Test plan
README.mdin GitHub's previewer; troubleshooting section is readable and each block follows the same shapeGenerated by Claude Code