# Troubleshooting

Source: https://getanalog.io/docs/troubleshooting/

Separate expected boundaries, fetching problems, and extraction problems.

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

<details class="reference-index">
<summary>On this page</summary>

- [First: is it a bug at all?](https://getanalog.io/docs/troubleshooting/#first-is-it-a-bug-at-all)
- [Check the environment](https://getanalog.io/docs/troubleshooting/#check-the-environment)
- [Check the saved page](https://getanalog.io/docs/troubleshooting/#check-the-saved-page)
- [Report what remains](https://getanalog.io/docs/troubleshooting/#report-what-remains)

</details>

## 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](https://getanalog.io/docs/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

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](https://getanalog.io/docs/authenticate/).
- **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](https://getanalog.io/docs/cli-reference/#analog-browser-install).

The credential check is local. If a configured credential is rejected,
use [`analog whoami --verify`](https://getanalog.io/docs/cli-reference/#analog-whoami) to
check whether Analog accepts it.



### Check what is available here

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

```bash wrap=true example=runnable scenario=cli-doctor-connected
analog doctor
```

```text wrap=true example=output scenario=cli-doctor-connected
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

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](https://getanalog.io/docs/fetching/), 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](https://getanalog.io/docs/feedback/).



### Reopen the preview

Replace `<handle>` with the saved result's handle or name. Use
[`analog history`](https://getanalog.io/docs/cli-reference/#analog-history) to find it:

```bash wrap=true example=illustrative
analog view <handle>
```

Read the coverage notes before deciding that content was lost.

### Read the saved page as Markdown

```bash wrap=true example=illustrative
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

```bash wrap=true example=illustrative
analog view <handle> --json
```

Check the records under `structured_content` to inspect values beyond
the preview's field metadata. [Working with results](https://getanalog.io/docs/results/)
shows how to inspect a section and find particular records.



## 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](https://getanalog.io/docs/feedback/) owns the reason labels, privacy
contract, and submission examples for the CLI, MCP, and Python.