Could not connect to DynamoDB Local (ECONNREFUSED)

TL;DR — İstemcinizin aradığı yerde hiçbir şey dinlemiyor. DynamoDB Local'in beklediğiniz portta gerçekten çalıştığını ve istemcinizin endpoint'inin gerçek AWS'yi değil http://localhost:8000'i gösterdiğini doğrulayın.

Ne anlama gelir

Error: connect ECONNREFUSED 127.0.0.1:8000

TCP bağlantısı reddedildi: emülatör o ana bilgisayarda/portta çalışmıyor ya da istemci hiçbir şeyin dinlemediği bir yeri gösteriyor.

Neden olur

DynamoDB Local çalışmıyor — hiç başlamadı, çöktü ya da kapatıldı (başlatma süreci hatasına bakın).
Yanlış port — Local 8000'de ama istemci 8080'i arıyor (ya da kapsayıcı farklı bir ana bilgisayar portu eşliyor).
endpoint ayarlı değil — o olmadan SDK localhost'a değil, gerçek AWS'ye konuşur (ki bu sonra kimlik doğrulama/bölge hatası olarak ya da ana bilgisayarı geçersiz kıldıysanız reddedilme olarak belirir).
Docker ağı — başka bir kapsayıcıdan localhost, ana bilgisayar değil, o kapsayıcıdır. Hizmet adını / ana bilgisayar ağ geçidini kullanın.
localhost ile 127.0.0.1 çözümleme tuhaflıkları (IPv6 ::1).

Tipik kurulumlar

Kurulum	Uç nokta	Tuzak
Docker varsayılanı	`http://localhost:8000`	Konteyner `-p 8000:8000` yayımlamalıdır
Özel port	`http://localhost:8001`	`-port 8001`'i jar'da ve istemcide eşleştirin
Compose servisi	`http://dynamodb:8000`	Başka bir konteynerden — `localhost` değil
Yanlışlıkla gerçek AWS	`https://dynamodb.<region>.amazonaws.com`	Bulutu kastediyorsanız `endpoint`'i kaldırın

Windows'ta WSL ile ana makine bazen localhost:8000'in hangi sürece ait olduğu konusunda anlaşamaz — curl WSL'de çalışıyor ama ana makinedeki Node ECONNREFUSED alıyorsa, ana makine istemcisini açıkça 127.0.0.1'e yöneltin ya da Local'i istemcinin çalıştığı yerde çalıştırın.

Bir Local profilinde DynoTable'ın Bağlantıyı Test Et düğmesi, yapılandırdığınız uç noktada bir şeyin yanıt verdiğini doğrulamanın en hızlı yoludur — Local kapalıyken aynı reddedilen soketle başarısız olur.

Nasıl düzeltilir

Dinlediğini doğrulayın:

curl http://localhost:8000        # DynamoDB Local returns a small response
lsof -i :8000                     # something should own the port

İstemcide uç noktayı açıkça ayarlayın:

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
const client = new DynamoDBClient({
  region: 'local',
  endpoint: 'http://localhost:8000',
  credentials: {accessKeyId: 'local', secretAccessKey: 'local'}
});

Emülatörün gerçekten bağlandığı portla eşleştirin (ve Docker -p host:container eşlemesi).
Kapsayıcılar arası mı? localhost yerine kapsayıcı/hizmet adını (örneğin http://dynamodb-local:8000) veya host.docker.internal'ı kullanın (host.docker.internal Docker Desktop'ta otomatik çözümlenir; Linux Docker Engine'de --add-host host.docker.internal:host-gateway ekleyin).

DynoTable workbench

Install DynoTable ve ardından Ayarlar → Profiller → Profil Ekle ile bitiş noktası http://localhost:8000. Yerel profile geçmek için ⌘P tuşuna basın curl http://localhost:8000 başarılı olduğunda. Kimlik bilgisi noktası yeşil kalmalıdır Yerel açıkken; bağlantı hatalarıyla kırmızıya dönerse, bağlantı noktası veya uç nokta profil emülatörün dinlediği yerle eşleşmiyor. Şunu kullanın: DynamoDB JSON converter sonrasında demirbaşları yüklemek için Yerel ulaşılabilir.

curl http://localhost:8000 başarısız olursa emülatör çalışmıyor demektir; Docker'ı başlatın veya önce kavanozu (Unable to start DynamoDB Local process) kullanın. Bağlantı noktası yanlışsa ancak bir şey dinliyorsa genel bir HTTP hatası görebilirsiniz ECONNREFUSED yerine; profil uç noktasını herhangi bir şeyle eşleştirin raporlar. Kılavuz: Connect to DynamoDB Local & LocalStack.

İlgili hatalar

Kaynaklar

Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (default port 8000, launch command, Docker run/compose examples)
DynamoDB local usage notes — AWS DynamoDB Developer Guide (local endpoint http://localhost:8000; SDKs require an access key + region value)
amazon/dynamodb-local — Docker Hub (official image, docker run -p 8000:8000 amazon/dynamodb-local)
docker run --add-host — Docker CLI reference (host.docker.internal / host-gateway for container-to-host connections)

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.