Port already in use hatası nasıl çözülür? Adım adım rehber

Kısa yanıt

Port already in use hatası, başlatmaya çalıştığınız sunucunun istediği portu başka bir sürecin zaten dinlediği anlamına gelir; sorun ağ bağlantısında değil, aynı porta iki sürecin birden bağlanamamasındadır. Hangi sürecin o portu tuttuğunu bulup kapatmak veya sunucuyu farklı bir portta başlatmak, hatayı genellikle saniyeler içinde çözer.

Port already in use hatası ne anlama gelir?

İşletim sistemleri, bir ağ portunu aynı anda yalnızca tek bir sürece tahsis eder. Bir Node.js sunucusu, bir geliştirme ortamı ya da bir veritabanı istemcisi listen() çağrısıyla belirli bir porta bağlanmaya çalıştığında, o port başka bir program tarafından zaten tutuluyorsa işletim sistemi isteği reddeder ve terminalde port already in use hatası görünür. Node.js dünyasında bu durumun teknik kodu EADDRINUSE’dur; tam hata satırı genellikle Error: listen EADDRINUSE: address already in use :::3000 biçimindedir ve sonundaki sayı, çakışmanın yaşandığı port numarasını gösterir.

Bu hatanın kafa karıştırıcı tarafı, çoğu zaman kodunuzda hiçbir hata olmamasıdır. Sunucu mantığı tamamen doğru çalışsa da, aynı makinede önceden açılmış ve kapanmamış bir süreç portu elinde tuttuğu sürece yeni sunucu ayağa kalkamaz. Bu yüzden ilk refleks kodu incelemek değil, o portu kimin kullandığını bulmak olmalıdır.

Bu hata Node.js’e özgü değildir; aynı mantık Python’da Flask veya Django geliştirme sunucusunda, Ruby’de Rails’de, Java’da Spring Boot’ta ve hatta bir PostgreSQL veya MySQL istemcisinde de aynı şekilde işler, çünkü port tahsisi uygulama çerçevesinin değil, işletim sisteminin ağ katmanının sorumluluğudur. Hata mesajının kelimeleri dilden dile küçük farklar gösterebilir, ama kök neden her zaman aynıdır: iki süreç aynı porta birden bağlanamaz.

Bu hatayı en çok hangi işlemler tetikler?

Geliştiricilerin port already in use hatasıyla en sık karşılaştığı an, bir geliştirme sunucusunu terminalde kapatmadan aynı pencereyi kapatıp yeni bir terminalden tekrar başlatmaya çalıştıkları andır; eski süreç arka planda hâlâ çalışır ve portu bırakmaz. Nodemon veya Vite gibi otomatik yeniden başlatma araçları da bir çökme sonrasında eski süreci tam olarak sonlandıramadığında aynı sonucu doğurur. Bir uygulamayı yanlışlıkla iki farklı terminal sekmesinden başlatmak, bir önceki test koşusunun sunucusunu kapatmayı unutmak ve Docker container’ını durdurmadan yenisini çalıştırmaya çalışmak da bu listenin başında gelir.

Daha az bilinen bir tetikleyici, bazı sistem servislerinin yaygın geliştirme portlarını (örneğin 5000 veya 7000) arka planda zaten kullanmasıdır; bu durumda hata sizin kodunuzdan değil, makinenizdeki başka bir yazılımdan kaynaklanır ve teşhis biraz daha uzun sürer.

Port already in use hatası nasıl çözülür?

Ki adımları sırayla izlemeniz, önce sorunu teşhis etmenizi, ardından en az riskli çözümü uygulamanızı sağlar.

1. Portu kullanan süreci bulun

MacOS ve Linux’ta lsof -i :3000 komutu, belirtilen portu dinleyen sürecin adını ve işlem kimliğini (PID) listeler. Windows’ta aynı bilgiye netstat -ano | findstr :3000 komutuyla ulaşılır; çıktıdaki son sütun PID numarasını gösterir. Linux’ta ss -tulpn | grep 3000 komutu da benzer bir sonuç verir ve bazı dağıtımlarda lsof’tan daha hızlı çalışır.

İşletim sistemi	Portu bulma komutu	Süreci sonlandırma komutu
macOS / Linux	lsof -i :3000	kill -9 <PID>
Linux (alternatif)	ss -tulpn | grep 3000	kill -9 <PID>
Windows	netstat -ano | findstr :3000	taskkill /PID <PID> /F

2. Süreci güvenli şekilde sonlandırın

PID’yi bulduktan sonra macOS veya Linux’ta kill -9 <PID> komutu süreci zorla kapatır; Windows’ta karşılığı taskkill /PID <PID> /F komutudur. Kapatmadan önce o PID’nin gerçekten beklediğiniz uygulamaya ait olduğunu kontrol etmek iyi bir alışkanlıktır, çünkü aynı portu bazen sistemin kendisine ait bir arka plan servisi tutabilir. npx kill-port 3000 gibi küçük bir yardımcı araç, işletim sistemi farkını ortadan kaldırıp aynı işlemi tek komutla yapar.

3. Farklı bir port numarası kullanın

Portu tutan süreci kapatmak her zaman mümkün veya istenen bir seçenek olmayabilir, özellikle o süreç başka bir ekip üyesine veya kritik bir servise aitse. Bu durumda uygulamanızı farklı bir portta başlatmak çoğu zaman en hızlı çözümdür; çoğu çerçeve bunu bir ortam değişkeni veya komut satırı parametresiyle destekler, örneğin PORT=3001 npm start. Port numarasını kodda sabit yazmak yerine ortam değişkeninden okumak, aynı çakışmayla ileride tekrar karşılaşma olasılığını da düşürür.

4. Docker container’larında portu serbest bırakın

Docker kullanıyorsanız hata genellikle ana makinedeki port eşlemesinden kaynaklanır. docker ps komutu hangi container’ın hangi portu tuttuğunu gösterir; ilgili container’ı docker stop <container_id> ile durdurmak portu serbest bırakır. docker-compose.yml dosyasındaki port eşlemesini ("3000:3000" gibi) farklı bir ana makine portuna çevirmek, container içindeki uygulamayı değiştirmeden çakışmayı ortadan kaldıran başka bir yoldur.

CI/CD ve ekip ortamında bu hata neden tekrar eder?

Aynı sunucuda birden fazla projenin paralel çalıştığı derleme sunucularında, bir önceki test koşusunun kapanmayı unuttuğu bir süreç sonraki koşuyu doğrudan engelleyebilir. Bu riski azaltmanın en sağlam yolu, test ve entegrasyon betiklerinde portu sabit bir sayı olarak değil, her çalıştırmada rastgele veya ortam değişkeninden gelen bir değer olarak seçmektir. Sunucu kapanış mantığına SIGTERM sinyalini doğru işleyen bir temiz kapanma (graceful shutdown) bloğu eklemek de sürecin portu arkasında bırakmadan sonlanmasını garanti eder.

Ekip içinde birden fazla geliştiricinin aynı varsayılan portu (3000, 5000, 8080 gibi) kullandığı projelerde, .env dosyasında projeye özgü bir port numarası tanımlamak, farklı projelerin aynı makinede aynı anda çalıştırılmaya çalışılmasından kaynaklanan çakışmaları büyük ölçüde azaltır. Birden fazla mikroservisi yerel makinede aynı anda çalıştıran ekipler için her servise ayrı bir port aralığı ayırmak ve bu aralığı proje belgelerinde yazılı tutmak, yeni katılan bir geliştiricinin ilk gününde port already in use hatasıyla boğuşmasını da önler.

Sık yapılan hatalar

Hata mesajını okumadan doğrudan bilgisayarı yeniden başlatmak, sorunu çözer gibi görünse de aynı hatayla kısa süre sonra tekrar karşılaşmanıza yol açabilir; asıl kalıcı çözüm süreci bulup doğru kapatmaktır. PID’yi doğrulamadan kill -9 komutunu rastgele bir sürece uygulamak, henüz kaydedilmemiş bir işin veya başka bir uygulamanın beklenmedik şekilde kapanmasına neden olabilir. Port numarasını kodun içine sabit yazıp ortam değişkenine taşımamak, aynı çakışmanın her yeni ortamda tekrar yaşanmasını garantiler. Docker kullanırken container’ı durdurmadan docker-compose up komutunu tekrar çalıştırmak da bu listenin sık görülen bir diğer örneğidir.

Kontrol listesi

Önce hangi port numarasının çakıştığını hata mesajından okuyun. Ardından lsof veya netstat ile o portu tutan süreci ve PID’sini bulun. PID’nin beklediğiniz uygulamaya ait olduğunu doğruladıktan sonra süreci sonlandırın veya uygulamayı farklı bir portta yeniden başlatın. Docker kullanıyorsanız docker ps ile ilgili container’ı tespit edip durdurun. Son olarak, port numarasını koddan ortam değişkenine taşıyarak aynı hatanın tekrarını önleyin.

Sonraki adım

Port already in use hatası, görünüşünün aksine kodunuzdaki bir kusurdan değil, işletim sisteminin aynı porta iki süreci birden bağlamayı engellemesinden kaynaklanır ve doğru teşhisle birkaç dakikada çözülür. Projenizin geliştirme ortamını, CI/CD hattını veya Docker tabanlı altyapısını baştan sağlam kurmak isterseniz, grup şirketimiz Web Tasarım Ofisi yazılım altyapısı ve sunucu yapılandırması konularında destek sağlıyor.

Node.js tabanlı projelerinizi profesyonel bir ekiple kurmak için özel yazılım hizmetimizi inceleyebilir ya da bizimle iletişime geçebilirsiniz. Kurulum sırasında karşılaşabileceğiniz başka bir yaygın engeli npm install hatası rehberimizde, kod gönderirken çıkabilecek bir sorunu da git push rejected hatası rehberimizde ayrıntılı olarak ele alıyoruz.

Kaynaklar

• Node.js resmî dokümantasyonu, Common System Errors, EADDRINUSE dahil yaygın sistem hatalarının resmî teknik açıklaması