Claude Code: ECONNREFUSED (connection refused) - jak naprawić

Claude Code

Claude Code: ECONNREFUSED (connection refused) - jak naprawić

W skrócie

ECONNREFUSED to jednoznaczny sygnał: Claude Code zapukał pod konkretny adres i port, ale nikt tam nie odpowiedział, bo nic nie nasłuchuje. W kontekście narzędzia najczęściej chodzi o lokalny serwer MCP albo proxy. Pokazujemy, jak to poskładać.

Jak to wygląda w praktyce

W terminalu pojawia się connection refused albo błąd z kodem ECONNREFUSED, często z podanym adresem i numerem portu, na przykład 127.0.0.1:3000. Połączenie jest odrzucane natychmiast, bez czekania.

Błąd towarzyszy zwykle uruchamianiu serwera MCP albo próbie połączenia z lokalnym proxy - operacja nie startuje, bo docelowa usługa nie odpowiada.

Dlaczego tak się dzieje

ECONNREFUSED oznacza, że pod danym adresem i portem nie ma niczego, co przyjęłoby połączenie. System aktywnie je odrzuca, zamiast czekać. To zasadnicza różnica względem timeoutu - tu odpowiedź jest natychmiastowa i jednoznaczna: nikt nie słucha.

W Claude Code najczęściej dotyczy to lokalnego serwera MCP albo lokalnego proxy, który nie wstał, wywalił się przy starcie albo słucha na innym porcie niż ten wpisany w konfiguracji. Znacznie rzadziej winny jest firewall, który blokuje i odrzuca ruch do danego portu.

Jak to rozwiązać krok po kroku

1. Ustal, jaki adres i port jest w komunikacie błędu, a następnie sprawdź, czy usługa naprawdę tam działa: curl -v http://127.0.0.1:PORT z właściwym numerem portu.
2. Sprawdź, czy proces w ogóle nasłuchuje na tym porcie. Na Windows użyj netstat -ano | findstr :PORT - brak wpisu oznacza, że nikt tam nie słucha.
3. Jeśli usługa nie działa, uruchom ją. Serwer MCP albo lokalny proxy musi być wystartowany, zanim Claude Code spróbuje się z nim połączyć.
4. Porównaj port i adres w konfiguracji z tym, na którym usługa faktycznie nasłuchuje. Literówka w numerze portu albo localhost zamiast właściwego adresu to najczęstsza przyczyna.
5. Popraw konfigurację MCP albo proxy tak, żeby wskazywała na działający port i adres, i zrestartuj Claude Code.
6. Jeśli usługa działa, a połączenie nadal jest odrzucane, sprawdź firewall - upewnij się, że nie blokuje ruchu lokalnego na tym porcie.

Jak sprawdzić, że zadziałało

Po uruchomieniu usługi i poprawie konfiguracji test curl -v http://127.0.0.1:PORT powinien nawiązać połączenie i coś zwrócić, zamiast natychmiast je odrzucić. To potwierdza, że pod tym adresem ktoś już nasłuchuje.

Następnie ponów operację w Claude Code, która wcześniej dawała ECONNREFUSED. Jeśli przechodzi, adres i port zgadzają się z działającą usługą i połączenie jest przyjmowane.

Wróć do listy problemów z Claude Code

Szkolenie Claude Code - od zera do zespołu agentów AI -->

Szkolenie Claude Code - od zera do zespołu agentów AI

Tryb planowania, tryby uprawnień, komendy, MCP, hooki i systemy multi-agent - wszystko na żywym kodzie podczas trzydniowego szkolenia. Prowadzi Łukasz Matuszewski. Szkolenie ma terminy gwarantowane - odbędzie się niezależnie od liczby zgłoszeń.

Sprawdź szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5