--hostname requires sudo when bound to domain and port below 1024

[FezVrasta]

Summary

I noticed if I run next -p 1023 --hostname example.org on macOS, the script will fail unless I run it with sudo. But if I just run next -p 1023 it will bind the port successfully without root permissions.

If the problem was the low port number I would expect sudo to be required no matter if I try to bind it to a hostname or leave the default one set.

❯ next -p 1023
  ▲ Next.js 14.2.11
  - Local:        http://localhost:1023

 ✓ Starting...

                                                                                                                                                                              
❯ next -p 1023 --hostname=localhost
 ⨯ Failed to start server
Error: listen EACCES: permission denied ::1:1023
    at Server.setupListenHandle [as _listen2] (node:net:1855:21)
    at listenInCluster (node:net:1920:12)
    at GetAddrInfoReqWrap.doListen [as callback] (node:net:2075:7)
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (node:dns:109:8) {
  code: 'EACCES',
  errno: -13,
  syscall: 'listen',
  address: '::1',
  port: 1023
}

❯ next -p 1023 --hostname=0.0.0.0  
  ▲ Next.js 14.2.11
  - Local:        http://localhost:1023
  - Network:      http://0.0.0.0:1023

 ✓ Starting...
 ✓ Ready in 5.8s

❯ next -p 1023 --hostname=127.0.0.1
 ⨯ Failed to start server
Error: listen EACCES: permission denied 127.0.0.1:1023
    at Server.setupListenHandle [as _listen2] (node:net:1855:21)
    at listenInCluster (node:net:1920:12)
    at doListen (node:net:2075:7)
    at process.processTicksAndRejections (node:internal/process/task_queues:83:21) {
  code: 'EACCES',
  errno: -13,
  syscall: 'listen',
  address: '127.0.0.1',
  port: 1023
}

Why is sudo required for this specific combination?

Additional information

No response

Example

No response

[Juneezee]

On my Linux machine, I do need sudo for both next dev -p 1023 and next dev -p 1023 --hostname localhost

next dev -p 1023

 ⨯ Failed to start server
Error: listen EACCES: permission denied 0.0.0.0:1023
    at Server.setupListenHandle [as _listen2] (node:net:1882:21)
    at listenInCluster (node:net:1961:12)
    at Server.listen (node:net:2063:7)
    at /home/jun/Desktop/myapp/node_modules/.pnpm/next@14.2.11_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/lib/start-server.js:280:16
    at new Promise (<anonymous>)
    at startServer (/home/jun/Desktop/myapp/node_modules/.pnpm/next@14.2.11_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/lib/start-server.js:191:11)
    at /home/jun/Desktop/myapp/node_modules/.pnpm/next@14.2.11_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/lib/start-server.js:310:52
    at Span.traceAsyncFn (/home/jun/Desktop/myapp/node_modules/.pnpm/next@14.2.11_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/trace/trace.js:154:26)
    at process.<anonymous> (/home/jun/Desktop/myapp/node_modules/.pnpm/next@14.2.11_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/next/dist/server/lib/start-server.js:310:35)
    at process.emit (node:events:519:28) {
  code: 'EACCES',
  errno: -13,
  syscall: 'listen',
  address: '0.0.0.0',
  port: 1023
}

next dev -p 1023 --hostname localhost

 ⨯ Failed to start server
Error: listen EACCES: permission denied ::1:1023
    at Server.setupListenHandle [as _listen2] (node:net:1882:21)
    at listenInCluster (node:net:1961:12)
    at GetAddrInfoReqWrap.doListen [as callback] (node:net:2135:7)
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (node:dns:111:8) {
  code: 'EACCES',
  errno: -13,
  syscall: 'listen',
  address: '::1',
  port: 1023
}

---

But if I just run next -p 1023 it will bind the port successfully without root permissions.

I googled "macos bind privileged ports" and this are the top 2 results:

1. https://forums.developer.apple.com/forums/thread/674179
2. https://zameermanji.com/blog/2024/1/5/binding-to-privileged-ports-without-root-on-macos/

So it seems like you don't need root permissions anymore to bind privileged ports since macOS Mojave (10.14).

[FezVrasta]

Thanks for double checking @Juneezee, this stil doesn't explain why adding --hostname makes sudo required again. The --hostname flag should not influence the need for root permissions from my understanding.

[Juneezee]

Thanks for double checking @Juneezee, this stil doesn't explain why adding --hostname makes sudo required again. The --hostname flag should not influence the need for root permissions from my understanding.

Unfortunately I don't have a macOS machine so I'm unable to troubleshoot further. But this does look like a macOS specific feature (?) to me.

The author of this blog post (https://zameermanji.com/blog/2024/1/5/binding-to-privileged-ports-without-root-on-macos/) also encountered the same issue:

For example running the following shows nc binding to port 81 without issue.

$ nc -l 0.0.0.0 81
^C

However binding to a port on a specific interface still requires root.

$ nc -l 127.0.0.1 81
nc: Permission denied

[FezVrasta]

I see, to be fair I would just need a way to change what the Next.js log displays and update the SSL certificate hostname, as I don't really need to bind to a specific port :-(

 ▲ Next.js 14.2.11
  - Local:        http://example.org:1023
  - Network:      http://example.org:1023

 ✓ Starting...
 ✓ Ready in 5.8s