Docker Error: endpoint with name already exists in network — Решение
Архитектура подсистемы libnetwork и симптомы коллизии
Ошибка endpoint with name already exists in network возникает в подсистеме libnetwork демона dockerd при попытке запустить контейнер или подключить его к мостовой (bridge) или оверлейной (overlay) сети, в которой предыдущая конечная точка (endpoint) с данным именем или интерфейсом veth осталась зарегистрированной в базе состояний демона. Это происходит при аварийном завершении контейнера (OOMKilled, kill -9 dockerd, panic ядра Linux) без выполнения процедуры graceful shutdown, из-за чего локальная база состояний kv/libnetwork рассинхронизируется с реальным состоянием сетевых пространств имен (netns).
Влияние на бизнес и инфраструктуру:
Полная остановка развертывания сервисов через CI/CD пайплайны, сбой автоматического перезапуска контейнеров orchestrator/compose, деградация доступности клиентских микросервисов и нарушение SLA.
Таблица параметров и сетевых сущностей
| Параметр / Сущность | Слой абстракции | Описание роли |
|---|---|---|
EndpointID | libnetwork sandbox | Уникальный хэш конечной точки сетевого интерфейса контейнера. |
vethXXXXXXX | Linux Kernel Network | Виртуальная пара сетевых интерфейсов между bridge хоста и netns контейнера. |
docker-net-bridge | Kernel Bridge / Netfilter | Виртуальный коммутатор, управляющий изоляцией и ARP-таблицами контейнеров. |
Пошаговое руководство по устранению зависшего эндпоинта
Сценарий 1: Принудительное отключение контейнера от сети
Если контейнер существует, но заблокирован в сети, используйте флаг принудительного разрыва соединения:
# Принудительное отключение контейнера от проблемной сети
docker network disconnect -f <network_name> <container_name_or_id>
# Повторный запуск контейнера
docker start <container_name_or_id>Сценарий 2: Поиск висячего эндпоинта через inspect сети
Если контейнер был удален, но сеть удерживает запись о нем:
# Просмотр активных эндпоинтов и IP-адресов в сети
docker network inspect <network_name>
# Пересоздание пользовательской сети при необходимости
docker network rm <network_name>
docker network create <network_name>Сценарий 3: Сброс локального кэша состояний libnetwork
В критических ситуациях, когда демон dockerd хранит битый statefile в /var/lib/docker/network/files/local-kv.db:
# Остановка Docker Daemon
systemctl stop docker
# Очистка локальной базы kv сетей (для standalone хостов)
rm -rf /var/lib/docker/network/files/local-kv.db
# Запуск демона Docker
systemctl start dockerТиповые ошибки администраторов
- Удаление файла local-kv.db в production Swarm-кластере: Это разрушает gossip-протокол overlay-сетей кластера.
- Игнорирование сетевых пространств имен: Попытка перезапускать compose-стек без предварительного вызова
docker compose down --remove-orphans.
Инженеры ITSTM выполнят глубокий аудит SDN, сетевых оверлеев и параметров dockerd, исключив сетевые конфликты и простои сервисов.
Частые вопросы (FAQ)
Почему ошибка появляется после перезагрузки хоста?
При некорректном выключении сервера (hard reset) Docker не успевает очистить состояние libnetwork, и при старте пытается повторно связать эндпоинт со старым netns.
Помогает ли команда docker system prune в данном случае?
Команда docker system prune удаляет только неиспользуемые сети. Если сеть назначена контейнеру, она не будет очищена без флага принудительного отключения.
Как предотвратить зависание эндпоинтов в CI/CD runners?
Всегда завершайте pipeline выполнением шагов trap/cleanup с вызовом docker compose down --volumes --remove-orphans.
Влияет ли ошибка на другие контейнеры в этой же сети?
Да, если зависший эндпоинт занял зарезервированный статический IP-адрес, новый контейнер с тем же адресом не сможет запуститься.
