claude-code - 💡(How to fix) Fix preview_screenshot times out (30s) when serving static HTML via python http.server [1 participants]

Description

preview_screenshot consistently times out after 30 seconds when the dev server is a Python http.server serving a static HTML site. All other preview tools work correctly in the same session.

Steps to reproduce

1. Create a .claude/launch.json with a Python HTTP server:

   {
     "version": "0.0.1",
     "configurations": [
       { "name": "site", "runtimeExecutable": "python", "runtimeArgs": ["-m", "http.server", "3457"], "port": 3457 }
     ]
   }

2. Call preview_start → succeeds
3. Call preview_snapshot → succeeds (returns full accessibility tree)
4. Call preview_console_logs → succeeds (no errors)
5. Call preview_network → succeeds (images and fonts load fine; JS eval confirms img.naturalWidth > 0)
6. Call preview_screenshot → times out after 30s

Expected behavior

preview_screenshot should return a JPEG of the rendered page, just like preview_snapshot does.

Actual behavior

preview_screenshot timed out after 30s. The preview window may be stuck (modal dialog, navigation hang, or unresponsive renderer).

No errors in console. No failed network requests (except a GA POST which is expected to fail on localhost). The page renders and is fully interactive.

Environment

• OS: Windows 11 Pro 10.0.26200
• Shell: bash (Git Bash)
• Claude Code version: current
• Server: python -m http.server 3457 (Python 3.x)
• Page: Static HTML with Alpine.js, Tailwind CSS (pre-built), inline SVGs — no heavy JS

Impact

Cannot visually verify UI changes via screenshot in the verification workflow. All other preview tools work normally.

Workaround

Use preview_snapshot (accessibility tree) to verify content and structure. preview_eval + DOM queries to check specific elements.

Notes

• preview_screenshot seems to fail only for this server type. May be related to how Chromium waits for the page to be "ready" before screenshotting, and Python's http.server doesn't set certain response headers that signal completion.
• Possible fix: add a configurable timeout or a "page idle" heuristic instead of relying on a navigation event.

🤖 Generated with Claude Code