Skip to content
Analog Docs

Troubleshooting

First: is it a bug at all?

Section titled “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

Section titled “The one-command triage: the markdown check”
Terminal window
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.

Reporting

Section titled “Reporting”
Terminal window
analog feedback quality <url> --reason <label> --note "expected X, got Y"

Labels (also enumerated in the MCP tool’s schema): undetected_block (the page was really a challenge or block that Analog mistook for content — the earliest symptom of that cascade), under_rendered (content the render missed), garbled_markdown (the page’s text came back mangled in the markdown — characters split apart or run together), no_records_found (the page plainly shows records but none came back), misfielded_values, page_chrome_in_records, wrong_content_extracted (three flavors of wrong-shaped output), over_extraction, under_extraction, poor_field_naming (minor damage), other (anything else).

A good report is one line: the URL, the handle, expected vs got. Extraction URLs are never logged. A quality report includes the URL you explicitly submit; it never includes page content.