Troubleshooting

Fix capture, target, and browser setup issues.

Most capture issues come from page state, selector ambiguity, browser setup, or unsupported DOM/CSS features. Start with the smallest retry that makes the page state and target clearer.

Start here

The wrong thing was captured.

Run domshot inspect, review candidates, narrow target, add kinds, or switch to selector mode.

The right thing exists but is hidden.

Add steps to click a tab, close a banner, scroll, wait, or open a modal before capture.

The page needs login.

Use CDP or profile mode so DOMShot can attach to a browser session where the user is already signed in.

The PNG exists but styling is limited.

Check fallback. If it is true, DOMShot used visible pixels because DOM rendering was blocked or unsupported.

Browser modes

Browser mode decides where DOMShot gets the page. Default launch is best for public pages. CDP and profile mode are for private pages, logged-in pages, or pages that need manual setup.

Launch

DOMShot starts Playwright Chromium and navigates to the URL. Use this for normal public pages.

CDP

DOMShot attaches to an existing Chrome session through a debugging port. Use this when the page is already open or logged in.

Profile

DOMShot launches Chrome with an explicit automation profile folder. Use this when you want a reusable automation browser profile.

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/.domshot/chrome-profile"

Use a dedicated automation profile. Do not point profile mode at your regular Chrome profile.

CDP in plain words: Chrome opens a local debugging port, and DOMShot connects to that browser instead of starting a fresh one.

Common issues

Most fixes make one of three things clearer: the browser state, the target description, or the exact selector.

Symptom	Likely cause	Fix
Playwright says Chromium is missing	Browser binary is not installed locally	Run `npx playwright install chromium` in the project.
`DOMSHOT_SELECTOR_NOT_FOUND`	Selector does not exist, is hidden, or page state is not ready	Check the selector, increase timeout, or wait for the page state.
`DOMSHOT_SELECTOR_NOT_UNIQUE`	Strict mode found multiple elements	Use a more specific selector or intentional `match: "first"`.
`DOMSHOT_TARGET_NOT_FOUND`	Target mode could not find a strong visible match	Use a clearer target, add steps, or use selector mode.
`DOMSHOT_TARGET_AMBIGUOUS`	Strict target matching found close candidates	Narrow the target phrase or use selector mode.
Wrong visual selected	Page has many similar elements or weak semantic labels	Run inspect, create a contact sheet, use `kinds`, narrow `target`, or use selector mode.
Cookie banner selected	Banner dominates the viewport	Close it with `steps` before inspection.
Lazy content missing	Content has not loaded before capture	Add scroll, wait, or `waitFor` steps.
Iframe or shadow DOM warning	Useful UI is inside an iframe or shadow host	Use selector mode for exact control when v1 cannot style the nested content.
Fallback screenshot used	DOM rendering was blocked or unsupported	Accept fallback if visible pixels are enough, or use `fallback: "throw"`.
CDP attach fails	Chrome was not started with remote debugging or port is wrong	Start Chrome with `--remote-debugging-port=9222` and pass the same endpoint.
Logged-in page opens logged out	Default launch mode started a fresh browser with no session	Use CDP attach or profile mode with a dedicated authenticated automation profile.
Shot pack includes weak images	The intent or target was too broad for the page	Use plan first, review rejected candidates, narrow `target`, or add `kinds`.

Retry playbook

Use this order when an agent needs to fix a bad capture. Each step adds only the amount of control needed.

Run domshot inspect with the same intent and target.
Create a contact sheet when visual comparison would help.
Narrow the request with target, kinds, and limit.
Add steps for cookie banners, tabs, modals, scroll, or delayed UI.
Use selector mode when exactness matters more than discovery.

The examples below first inspect candidates, then create a contact sheet so the agent or user can compare what DOMShot found.

domshot inspect https://example.com \
  --intent "pricing visuals" \
  --target "pricing cards" \
  --kinds pricing,card \
  --limit 8

domshot contact-sheet https://example.com \
  --intent "pricing visuals" \
  --target "pricing cards" \
  --out .domshot/contact-sheet.png

Next step: if the contact sheet shows the right element, capture it with domshot capture, capture-set, or shot-pack. If not, narrow the target or use a selector.

What fallback means

DOMShot first tries to render the selected element through the DOM so it can preserve clean styling and transparent backgrounds. Some pages block or break that render path because of CSP, canvas, complex CSS, iframes, or unsupported DOM features. When fallback is true, DOMShot used a visible screenshot of the element instead.

Fallback output can still be useful. Use fallback: "throw" only when the workflow must fail instead of accepting a visible-pixel screenshot.

Privacy-safe debugging

Treat screenshots, browser profiles, cookies, tokens, private URLs, selectors, and local reports as sensitive. Keep private outputs in ignored local folders and do not paste full private command output into public issues, docs, commits, or pull requests.