Skip to content
Analog Docs

Troubleshooting

View as Markdown

Start with the message Analog gave you. If a result was saved, you can inspect it without fetching the page again.

On this page

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.
  • “No structured sections were extracted from this page.” — inspect the page document before assuming why. The page may be prose, may contain no structured sections, or may contain only an interstitial. Analog does not guess the cause from provider scripts embedded in the page.
  • A local or private-network request was declined — Analog refuses direct targets and page-initiated requests that are not public. This can include a hostname that currently resolves to a private address. Reaching a trusted dev server or intranet host on purpose is --allow-private (allow_private=True). file: URLs are never fetched. See Security for the browser boundary. Not a bug.
  • analog assess recommended a direct read. Use local Markdown for that task, or choose a structured view to compare the result.

Check the environment

Section titled “Check the environment”

If a command cannot connect or start the browser, run analog doctor in the same terminal or agent environment. Read each check and its suggested remedy:

  • Credential missing: connect your account.
  • Network or backend unavailable: follow the reported connection guidance before retrying the page.
  • Browser missing: Analog downloads it on first use. You can also install it ahead of time.

The credential check is local. If a configured credential is rejected, use analog whoami --verify to check whether Analog accepts it.

This example has a connected account and the browser already installed.

Check what is available here

analog doctor
Output
Credential: configured (bound to https://api.getanalog.io)
Egress:     ok — getanalog.io reachable
Backend:    ok
Browser:    installed


Everything Analog needs is available here.

These checks passed. If the problem is specific to one website, continue with that page’s message and saved result; this report does not establish whether the site allows access or whether the result is complete.

Check the saved page

Section titled “Check the saved page”

Compare the preview and the saved page’s Markdown. Use the same handle for both so you are inspecting the same fetch.

  • The preview reports incomplete coverage: review the supported fetch options, such as --pages, --load-all, or --expand-all, if you need that content.
  • Content is missing or garbled in Markdown too: report what is absent or unreadable after checking coverage. This narrows the symptom to the page document; it does not establish whether fetching or Markdown conversion caused it.
  • Content is readable in Markdown but wrong in the records: inspect the full records before reporting an extraction problem. The preview shows field metadata and can omit hidden fields from its summary; it does not show record values.

If the saved document contains only a challenge or interstitial, it does not contain the intended page. An already reported site block is an expected boundary; an unrecognized block can be reported through Feedback.

Replace <handle> with the saved result’s handle or name. Use analog history to find it:

Reopen the preview

analog view <handle>

Read the coverage notes before deciding that content was lost.

Read the saved page as Markdown

analog view <handle> --markdown

Look for the content you expected to see in the records. This reads the saved page document without contacting the website or Analog.

Check the full records

analog view <handle> --json

Check the records under structured_content to inspect values beyond the preview’s field metadata. Working with results shows how to inspect a section and find particular records.

Report what remains

Section titled “Report what remains”

Report the earliest symptom you can see. You do not need to diagnose the cause. Describe what you expected and what the saved result shows. The Feedback guide owns the reason labels, privacy contract, and submission examples for the CLI, MCP, and Python.