Commit b3c1ad9e authored by Cursor Agent's avatar Cursor Agent

fix: detect cross-address-family port conflicts in next dev

On some platforms (notably macOS), server.listen() with no hostname
binds to IPv6 (::) which does not trigger EADDRINUSE when another
server is already listening on IPv4 (e.g., 127.0.0.1 or 0.0.0.0) on
the same port. This causes two dev servers to appear to share port 3000.

Add a proactive port availability check that tests both IPv4 (0.0.0.0)
and IPv6 (::) before calling server.listen(). When a conflict is
detected and allowRetry is enabled (default port), the server
automatically finds the next available port and shows a warning.

The existing EADDRINUSE error handler in server.on('error') is retained
as a fallback for same-address-family conflicts.
parent c2bba0ea
...@@ -14,6 +14,7 @@ import v8 from 'v8' ...@@ -14,6 +14,7 @@ import v8 from 'v8'
import path from 'path' import path from 'path'
import http from 'http' import http from 'http'
import https from 'https' import https from 'https'
import net from 'net'
import os from 'os' import os from 'os'
import { exec } from 'child_process' import { exec } from 'child_process'
import Watchpack from 'next/dist/compiled/watchpack' import Watchpack from 'next/dist/compiled/watchpack'
...@@ -118,6 +119,60 @@ async function getProcessIdUsingPort(port: number): Promise<string | null> { ...@@ -118,6 +119,60 @@ async function getProcessIdUsingPort(port: number): Promise<string | null> {
return pidPromise return pidPromise
} }
/**
* Check if a port is available on a specific host by attempting to bind to it.
* Returns true if available, false if in use (EADDRINUSE).
* Other bind errors (e.g., EADDRNOTAVAIL for missing IPv6) are treated as available.
*/
function isPortAvailableOnHost(port: number, host: string): Promise<boolean> {
return new Promise((resolve) => {
const tester = net.createServer()
tester.once('error', (err: NodeJS.ErrnoException) => {
resolve(err.code !== 'EADDRINUSE')
})
tester.once('listening', () => {
tester.close(() => resolve(true))
})
tester.listen(port, host)
})
}
/**
* Find an available port starting from the given port.
* Checks both IPv4 (0.0.0.0) and IPv6 (::) to detect cross-address-family
* conflicts that server.listen() alone may miss on some platforms (e.g., macOS
* where an IPv6 bind does not conflict with an existing IPv4 listener).
*/
async function findAvailablePort(
startPort: number,
hostname: string | undefined,
maxRetries: number
): Promise<{ port: number; retryCount: number }> {
let port = startPort
for (let retryCount = 0; retryCount <= maxRetries; retryCount++) {
const hostsToCheck = hostname !== undefined ? [hostname] : ['0.0.0.0', '::']
let available = true
for (const host of hostsToCheck) {
if (!(await isPortAvailableOnHost(port, host))) {
available = false
break
}
}
if (available) {
return { port, retryCount }
}
if (retryCount < maxRetries) {
port++
}
}
return { port, retryCount: maxRetries }
}
export interface StartServerOptions { export interface StartServerOptions {
dir: string dir: string
port: number port: number
...@@ -293,6 +348,21 @@ export async function startServer( ...@@ -293,6 +348,21 @@ export async function startServer(
let portRetryCount = 0 let portRetryCount = 0
const originalPort = port const originalPort = port
// Proactively detect port conflicts across address families.
// On some platforms (notably macOS), server.listen() with no hostname binds
// to IPv6 (::) which does not conflict with an existing IPv4 listener on the
// same port. This check catches those cross-family conflicts so the retry
// logic can find an available port before calling server.listen().
if (allowRetry && isDev) {
const { port: availablePort, retryCount } = await findAvailablePort(
port,
hostname,
10
)
portRetryCount = retryCount
port = availablePort
}
server.on('error', (err: NodeJS.ErrnoException) => { server.on('error', (err: NodeJS.ErrnoException) => {
if ( if (
allowRetry && allowRetry &&
......
...@@ -829,6 +829,37 @@ describe('CLI Usage', () => { ...@@ -829,6 +829,37 @@ describe('CLI Usage', () => {
) )
}) })
test('Allow retry when port is used by IPv4-only server', async () => {
let output = ''
let ipv4Server: ReturnType<typeof http.createServer> | undefined
let app: any
try {
// Start a server explicitly bound to IPv4 loopback (127.0.0.1:3000)
// to simulate a third-party server like Vite/vinext
ipv4Server = http.createServer((_, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain' })
res.end('OK')
})
await new Promise<void>((resolve, reject) => {
ipv4Server!.on('error', reject)
ipv4Server!.on('listening', () => resolve())
ipv4Server!.listen(3000, '127.0.0.1')
})
app = await runNextCommandDev([dirBasic], undefined, {
onStderr(msg) {
output += stripAnsi(msg)
},
})
} finally {
await killApp(app).catch(console.error)
await new Promise((resolve) => ipv4Server?.close(resolve))
}
expect(output).toMatch(/Port 3000 is in use/)
})
test('-p reserved', async () => { test('-p reserved', async () => {
const TCP_MUX_PORT = 1 const TCP_MUX_PORT = 1
const { stderr, stdout } = await runAndCaptureOutput({ const { stderr, stdout } = await runAndCaptureOutput({
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment