Troubleshooting

First: is it a bug at all?

Analog discloses rather than fails silently, so some “failures” are the product working:

• “robots.txt disallows fetching this page” — Analog respects robots.txt, always. Not a bug.
• “This page returned a bot-protection challenge (…)” — the site declined automated visitors; Analog reports it instead of sneaking. Not a bug — unless you believe the classification is wrong.
• A localhost, private-network, or file: address was declined — Analog fetches only public web addresses by default. Reaching a dev server or intranet host on purpose is --allow-private (allow_private=True). Not a bug.
• The fit check said skip. Use the direct-read tool for that task, or extract anyway to compare the result.

The one-command triage: the markdown check

analog open <handle>            # orientation view
analog open <handle> --markdown # the page as fetched

Look for your missing/garbled content in the markdown:

• Not in the markdown either → the fetch never captured it. Try the fetch knobs (--pages, --load-all, --expand-all) — the output’s own hints usually name the right one. Still missing? Report it as a fetch problem.
• In the markdown, wrong in the records → an extraction bug. Report it — these are the reports we most want.

One rule for cascades: report the earliest symptom you can see.

Report what remains

Once you know whether the problem happened during fetching or extraction, report the earliest symptom you can see. The Feedback guide owns the reason labels, privacy contract, and submission examples for the CLI, MCP, and Python.