Come risolvere "port already in use" (EADDRINUSE)

La tua applicazione si avvia senza problemi sul computer di sviluppo, ma sul server di produzione restituisce l'errore EADDRINUSE e si rifiuta di partire.

In breve: L'errore port already in use indica che un altro servizio di sistema sta già occupando la porta di rete che l'applicazione sta tentando di riservare, esattamente come due attività commerciali che cercano di utilizzare lo stesso indirizzo fisico. La soluzione consiste nell'identificare quale processo stia occupando la porta, valutare se deve rimanere in esecuzione e, di conseguenza, arrestarlo oppure riallocare l'applicazione su una porta libera. È fondamentale evitare l'interruzione arbitraria dei processi senza averne prima verificato la natura, poiché si rischia di compromettere altri siti web, database o worker in background.

Cosa significa "port already in use"?

Una porta di rete rappresenta un canale d'ingresso numerato all'interno del server.

Nonostante l'infrastruttura disponga di un unico indirizzo IP pubblico, essa può ospitare molteplici servizi simultaneamente. Le porte servono a instradare correttamente il traffico: un web server riceve le richieste pubbliche sulle porte 80 (HTTP) e 443 (HTTPS), un'applicazione Node.js può rimanere in ascolto a livello locale sulla porta 3000, mentre un database PostgreSQL o MySQL utilizza tipicamente la 5432 o la 3306.

L'errore si presenta solitamente con la seguente sintassi:

Error: listen EADDRINUSE: address already in use :::3000

Questo messaggio conferma che l'applicazione ha tentato di associare il proprio servizio alla porta 3000, ma questa risultava già impegnata. Il sistema operativo non consente a due processi distinti di effettuare il binding sullo stesso socket (indirizzo IP e porta) contemporaneamente.

Analogamente a uno stallo in un parcheggio: se uno spazio è già occupato da un veicolo, un secondo mezzo non può posizionarsi nel medesimo stallo.

Perché si verifica l'errore EADDRINUSE?

I motivi principali che generano un errore di tipo EADDRINUSE si riconducono a poche casistiche standard:

1. Istanza duplicata dell'applicazione: L'applicazione è stata avviata due volte oppure la versione precedente non è stata terminata correttamente a seguito di un deployment fallito. È un problema frequente con i server di sviluppo, le applicazioni Node.js o Python e i process manager.
2. Conflitto di porte tra progetti distinti: Due applicazioni differenti sono state configurate per utilizzare la medesima porta (es. porta 3000). Questo scenario non crea problemi in ambienti single-app, ma genera sovrapposizioni quando si ospitano più servizi sulla stessa macchina. Quando si gestiscono più siti web su un unico server, è opportuno assegnare a ogni applicazione una porta privata dedicata, lasciando che sia un reverse proxy a instradare le richieste. Per approfondire l'architettura ideale, consulta la nostra guida su come ospitare più siti web su un solo server.
3. Occupazione da parte dei web server di sistema: Servizi come Nginx, Apache o Caddy occupano direttamente le porte pubbliche 80 e 443. L'applicazione deve normalmente posizionarsi alle spalle di tali servizi su una porta interna privata, evitando di competere per l'interfaccia pubblica primaria.
4. Mappatura dei container Docker: Un container Docker potrebbe aver impegnato la porta dell'host, anche se la sua esecuzione è stata dimenticata. Se vuoi chiarire il funzionamento della rete in ambiente containerizzato, leggi Docker su un server per principianti.

Come risolvere "port already in use" in modo sicuro

Per risolvere la criticità occorre identificare il processo in ascolto (listener). Sui sistemi Linux, comandi come ss, lsof o la verifica dei processi attivi consentono di individuare il PID (Process ID) associato alla porta. In ambienti Docker, l'ispezione dei container attivi permette di verificare quali porte siano state esposte sull'host.

Una volta individuato il processo responsabile, è necessario valutare le azioni da intraprendere prima di procedere all'arresto:

• Se si tratta di una vecchia istanza della medesima applicazione: arresta il processo in modo pulito utilizzando lo strumento con cui è stato avviato (es. il process manager di sistema, il daemon runner o CLI di containerizzazione). Una chiusura controllata consente la corretta liberazione delle risorse di sistema.
• Se si tratta di un'applicazione diversa in produzione: non arrestare il processo. Modifica la configurazione allocando la nuova applicazione su una porta privata differente e aggiorna il reverse proxy affinché indirizzi il traffico al nuovo endpoint. Ad esempio, una prima app rimarrà in ascolto sulla porta 3000 e una seconda sulla 3001, mentre Nginx gestirà l'instradamento in base al dominio richiamato.
• Se il conflitto riguarda le porte 80 o 443: si raccomanda la massima cautela. Trattandosi delle porte trasmissioni standard per il traffico web pubblico, l'interruzione impropria del servizio associato può causare l'inaccessibilità di tutti i siti ospitati sul server. Se riscontri problemi di raggiungibilità del sito, consulta la guida diagnostica su perché il tuo sito non si carica per isolare l'origine dell'anomalia tra livello applicativo, web server e rete.

È consigliabile evitare l'uso immediato di comandi di chiusura forzata come kill -9. Sebbene utili in situazioni di emergenza, non modificano le policy dei gestori di servizio (es. systemd o pm2), che potrebbero riavviare automaticamente il processo rioccupando la porta pochi secondi dopo.

FAQ

**L'errore EADDRINUSE rappresenta una vulnerabilità di sicurezza?** No. Si tratta di un conflitto di configurazione a livello di sistema operativo causato da due programmi che richiedono la stessa risorsa di rete, non di una compromissione di sicurezza.

È possibile risolvere il problema modificando semplicemente il numero di porta? Sì, a condizione che non vi siano dipendenze rigide. Se domini, reverse proxy, health check o mappature di container referenziano la porta precedente, occorre aggiornare coerentemente l'intera catena di configurazione.

Perché l'applicazione si avvia in locale ma fallisce sul server? Il server di produzione potrebbe avere già in esecuzione servizi come Nginx, daemon Docker o altre istanze applicative attive. L'ambiente locale e il server remoto presentano uno stato delle porte in ascolto differente.

Perché la porta risulta nuovamente occupata dopo l'arresto del processo? Se il servizio è gestito da un orchestratore o da un gestore di processi con policy di riavvio automatico, il sistema provvederà a riattivarlo immediatamente. È necessario intervenire sulla configurazione del gestore di servizi e non solo sul singolo processo.

La soluzione intermedia

Server Manager semplifica l'organizzazione dei progetti mantenendo l'associazione tra porte, domini e regole di routing chiaramente tracciabile all'interno di un'unica interfaccia.

Questo approccio previene i disservizi legati all'errore port already in use: evita la presenza di vecchie istanze orfane, impedisce le sovrapposizioni di porte tra progetti distinti ed elimina il rischio di disattivare erroneamente il web server principale. La struttura dell'infrastruttura rimane perfettamente visibile nel tempo, rendendo immediata la comprensione delle scelte di allocazione delle porte.

Mantenendo il controllo completo del server, disporrai di un quadro architetturale chiaro che riduce drasticamente il rischio di generare regressioni su altri servizi durante la gestione delle applicazioni.

La corretta risoluzione dell'errore si ottiene quando l'applicazione si avvia senza restituire l'eccezione listen EADDRINUSE, la porta assegnata risulta associata in modo univoco al processo dedicato e il servizio risponde correttamente tramite il rispettivo nome a dominio.