Vite : Application works on localhost:5173 but not on 127.0.0.1:5173

Vite Application Not Accessible via 127.0.0.1:5173 (localhost vs. IP)

Understand why your Vite application might work on localhost:5173 but not 127.0.0.1:5173, and learn how to configure Vite for broader network access.

When developing web applications with Vite, you might encounter a peculiar issue: your application loads perfectly fine when accessed via http://localhost:5173 but fails to load or connect when you try to use http://127.0.0.1:5173. This discrepancy can be confusing, especially since localhost typically resolves to 127.0.0.1. This article delves into the common reasons behind this behavior and provides clear solutions to ensure your Vite application is accessible as expected, whether for local development or testing across devices on your network.

Understanding the Difference: localhost vs. 127.0.0.1

While localhost and 127.0.0.1 both refer to the local machine, there's a subtle but crucial difference in how operating systems and network configurations handle them. 127.0.0.1 is the standard IPv4 loopback address, explicitly pointing to the local machine's network interface. localhost, on the other hand, is a hostname that typically resolves to 127.0.0.1 (and sometimes ::1 for IPv6) via the /etc/hosts file (or C:\Windows\System32\drivers\etc\hosts on Windows). The key distinction often lies in how development servers, like Vite's dev server, bind to network interfaces.

flowchart TD
    A[User Accesses] --> B{"http://localhost:5173"}
    B --> C[DNS/Hosts File Resolution]
    C --> D[Resolves to 127.0.0.1]
    D --> E[Vite Dev Server (Default Bind: 127.0.0.1)]
    E --> F[Application Works]

    G[User Accesses] --> H{"http://127.0.0.1:5173"}
    H --> I[Direct IP Access]
    I --> J[Vite Dev Server (Default Bind: 127.0.0.1)]
    J --> K[Application Works]

    L[User Accesses] --> M{"http://192.168.1.X:5173"}
    M --> N[Direct IP Access (Network)]
    N --> O{Vite Dev Server Bind Configuration}
    O -->|Binds to 0.0.0.0| P[Application Works (Network)]
    O -->|Binds to 127.0.0.1| Q[Connection Refused (Network)]

Vite Dev Server Binding Behavior and Network Access

The Root Cause: Network Interface Binding

By default, many development servers, including Vite, bind to 127.0.0.1 (the loopback interface) for security and simplicity. This means the server is only listening for connections originating from the local machine itself. When you access localhost, your system correctly routes the request to 127.0.0.1, and the server responds. However, if you explicitly try to access 127.0.0.1 and there's a subtle network configuration or firewall rule that treats direct IP access differently than hostname resolution, or if you're trying to access it from another device on your network, the connection might fail. The most common scenario for 127.0.0.1 not working while localhost does is when the server is configured to bind to 0.0.0.0 (all network interfaces) but a firewall or network setting is blocking direct IP access, or when the server is strictly binding to localhost and not 127.0.0.1 in a way that causes issues. More often, the problem arises when you want to access the app from another device using your machine's actual network IP (e.g., 192.168.1.X), which requires the server to bind to 0.0.0.0.

Solution: Configuring Vite to Bind to All Network Interfaces

To ensure your Vite application is accessible via 127.0.0.1, localhost, and even your local network IP address (e.g., 192.168.1.X), you need to configure Vite's development server to listen on all available network interfaces. This is achieved by setting the server.host option to true or '0.0.0.0' in your vite.config.js file.

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    host: true, // This makes Vite listen on 0.0.0.0
    port: 5173, // Optional: specify port if different
  },
});

Configuring Vite to bind to all network interfaces (0.0.0.0)

Setting host: true tells Vite to listen on 0.0.0.0, which means it will accept connections from any IP address configured on your machine, including 127.0.0.1, localhost, and your local network IP. After making this change, restart your Vite development server. You should now be able to access your application using http://localhost:5173, http://127.0.0.1:5173, and potentially http://<your-local-ip>:5173 from other devices on the same network (assuming no firewall blocks).

Troubleshooting Further Issues

If configuring host: true doesn't resolve the issue, consider these additional troubleshooting steps:

1. Check Firewall Settings

Ensure your operating system's firewall (e.g., Windows Defender Firewall, ufw on Linux, macOS Firewall) is not blocking incoming connections on port 5173. You might need to add an exception for this port or for Node.js/Vite.

2. Verify Network Connectivity

If trying to access from another device, ensure both devices are on the same network and can ping each other. Use ipconfig (Windows) or ifconfig/ip a (Linux/macOS) to find your machine's local IP address.

3. Inspect package.json Scripts

Sometimes, package.json scripts might override Vite's configuration. Ensure your dev script doesn't explicitly set a host that conflicts with your vite.config.js.

4. Clear Browser Cache

Browser caching can sometimes cause stale connection issues. Try clearing your browser's cache or using an incognito/private browsing window.

5. Check for Port Conflicts

Ensure no other application is already using port 5173. You can check this using tools like netstat or lsof.