DynamoDB Local: Address already in use (port 8000)

En bref — DynamoDB Local lie le port 8000 par défaut, et quelque chose le détient déjà — un DynamoDB Local antérieur que tu n'as pas arrêté, un autre service, ou un serverless-offline/conteneur en double. Libère le port 8000 ou démarre Local sur un port différent avec -port (et pointe ton client dessus).

Ce que ça signifie

Exception in thread "main" java.net.BindException: Address already in use
   ... Failed to bind to port 8000

DynamoDB Local est un processus Java qui ouvre un socket d'écoute sur le port 8000. Si ce port est déjà lié, la JVM ne peut pas le revendiquer et sort avec BindException. C'est purement un conflit de port local — rien à voir avec AWS ou les identifiants.

Pourquoi ça arrive

• Un DynamoDB Local précédent tourne encore — un java -jar DynamoDBLocal.jar (ou docker run) antérieur que tu n'as jamais arrêté.
• Un autre service détient le 8000 — un serveur de dev, un proxy, ou une application sans rapport sur le même port.
• Outillage en double — serverless-dynamodb-local et serverless-offline essayant tous deux de lier le 8000, ou deux stacks docker-compose up.
• Une instance plantée a laissé le port lié brièvement (TIME_WAIT), ou un conteneur zombie.

Serverless et lanceurs de tests

Le plugin serverless-dynamodb-local et les hooks globalSetup de Jest démarrent souvent Local implicitement — si tu lances en plus docker run -p 8000:8000 amazon/dynamodb-local à la main, la seconde tentative de bind meurt avec BindException alors même que Local est déjà en bonne santé. Choisis un seul lanceur par session de machine.

Sur macOS, les processus Java orphelins d'un lanceur de tests d'IDE sont un coupable fréquent — lsof -i :8000 montre souvent java avec un PID issu d'une exécution Gradle antérieure.

Comment le corriger

1. Trouve ce qui détient le port :

   lsof -i :8000                       # macOS / Linux
   netstat -ano | findstr :8000        # Windows (note the PID)

   CopierCopié
2. Arrête ce processus (ou l'ancien DynamoDB Local) :

   kill <PID>                          # macOS / Linux
   taskkill /PID <PID> /F              # Windows

   CopierCopié
3. Ou lance DynamoDB Local sur un port différent et mets à jour ton client :

   java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -port 8001
   # then: endpoint = http://localhost:8001

   CopierCopié
4. Docker ? Change le côté hôte du mappage (-p 8001:8000) et connecte-toi au 8001.
5. Retire les plugins/stacks en double pour qu'un seul processus tente de lier le port.

Dans DynoTable

Une fois le port 8000 libéré (ou Local déplacé sur -port 8001), installe DynoTable et ajoute un profil Local dans Settings → Profiles → Add Profile : mets l'endpoint http://localhost:8000 (ou ton port de remplacement), une région factice et des identifiants factices alphanumériques. Test Connection confirme que l'émulateur écoute avant que tu ne parcoures les tables. Marche à suivre : Running DynamoDB Local · Se connecter à DynamoDB Local et LocalStack.

Quand tu changes de port, mets l'endpoint du profil en cohérence — un profil qui pointe encore sur :8000 alors que Local écoute sur :8001 produit un connection refused même une fois le conflit de bind résolu. Le convertisseur JSON DynamoDB aide à charger des données de départ une fois Local joignable.

Erreurs liées

• Unable to start DynamoDB Local process — l'émulateur échoue à démarrer pour d'autres raisons (Java, bibliothèques natives).
• Could not connect to DynamoDB Local (ECONNREFUSED) — le revers : rien n'écoute là où tu composes.
• Apprends : Running DynamoDB Local

Sources

• Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (default port 8000; "If port 8000 is unavailable, this command throws an exception")
• DynamoDB local usage notes — AWS DynamoDB Developer Guide (the -port command line option and full flag list)
• amazon/dynamodb-local — Docker Hub (official image and port mapping)

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.