Preview pane connects via 127.0.0.1 instead of localhost, fails on macOS IPv6

Resolved 💬 2 comments Opened Mar 3, 2026 by apcj Closed Mar 3, 2026

Problem

The Claude Preview pane connects to dev servers using 127.0.0.1:<port>, but many dev servers (e.g. Astro) bind to localhost by default, which on macOS resolves to ::1 (IPv6). This causes ERR_CONNECTION_REFUSED in the preview pane, even though the server is running and accessible at localhost:<port> in a regular browser.

Steps to reproduce

  1. Configure .claude/launch.json to start a dev server (e.g. Astro on port 4321):

``json
{
"version": "0.0.1",
"configurations": [
{
"name": "dev",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 4321
}
]
}
``

  1. Start the server with preview_start
  2. The preview pane shows a blank/black page

Expected behavior

The preview pane should load the page successfully, the same as visiting localhost:4321 in Chrome.

Actual behavior

All network requests from the preview pane fail with ERR_CONNECTION_REFUSED because they target 127.0.0.1:4321 (IPv4) while the server is listening on ::1:4321 (IPv6 localhost).

Workaround

Adding --host 0.0.0.0 to the dev server command makes it bind to all interfaces, which fixes the preview but unnecessarily exposes the dev server to the local network.

Suggested fix

The preview pane should connect via localhost instead of 127.0.0.1, so it resolves to whatever address the server is actually listening on.

Environment

  • macOS (Darwin 24.6.0)
  • Astro v5.16.9
  • Claude Code CLI

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗