testcontainers / testcontainers/testcontainers-python

Bug: Failure to connect to Reaper leaves stale ryuk containers, leading to container name collisions

Open
#1,093 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
2.3k
Forks
386
Avg merge
4h 40m
Merged PRs (30d)
1

Description

Describe the bug

Running testcontainers in a network-isolated environment leaves stale ryuk containers. Further down this produces misleading error messages about duplicate containers.

  1. Reaper._create_instance starts a new ryuk container
  2. Reaper._create_instance fails to connect to the reaper container.
    Line 372 s.connect((container_host, container_port)) raises ConnectionRefusedError: [Errno 111] Connection refused
  3. Reaper._create_instance leaves the container running, without assigning it to Reaper._instance
  4. Test fails with Connection refused error message above
  5. Next test starts
  6. Reaper._create_instance attempts starting a new ryuk container. Fails with misleading error message: requests.exceptions.HTTPError: 409 Client Error: Conflict for url: http+docker://localhost/v1.55/containers/create?name=testcontainers-ryuk-6810abc7-a781-44ec-928a-2c671c8881d9. Normally this should reuse the Reaper._instance but since it was never assigned it will not realize that it is already running. The unique ID is only generated once per session.
  7. Second test fails with the misleading message about duplicate ryuk containers.

To Reproduce

Run a pytest suite having at least 2 tests attempting to use testcontainers in a network-isolated environment, such as Bazel with tags=["block-network"]

BUILD.bazel

load("@rules_python//python:defs.bzl", "py_test")

py_test(
    name = "test_ryuk_repro",
    srcs = ["test_ryuk_repro.py"],
    tags = ["block-network"],
    deps = [
        "@pip//pytest:pkg",
        "@pip//testcontainers:pkg",
    ],
)

test_ryuk_repro.py

import pytest
from testcontainers.core.container import DockerContainer

def test_a():
    with DockerContainer("hello-world"):   # Fails with ConnectionError
        pass

def test_b():
    with DockerContainer("hello-world"):   # Fails with 409 Conflict error
        pass

Runtime environment

Provide a summary of your runtime environment. Which operating system, python version, and docker version are you using? What is the version of testcontainers-python you are using? You can run the following commands to get the relevant information.

# Get the operating system information (on a unix os).
$ uname -a
Linux ... 7.0.0-27-generic #27-Ubuntu SMP PREEMPT_DYNAMIC Thu Jun 18 19:13:49 UTC 2026 x86_64 GNU/Linux
# Get the python version.
$ python --version
3.11
$ docker info
Client: Docker Engine - Community
 Version:    29.6.1
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.35.0
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v5.3.1
    Path:     /usr/libexec/docker/cli-plugins/docker-compose

$ pip freeze
testcontainers==4.14.2

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in Reaper._create_instance, especially the connection at line 372, and reproduce the failure with the two-test pytest example in a network-isolated environment. Trace what happens when the connection is refused and verify that a later test does not encounter a stale ryuk container or a misleading 409 name-conflict error.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, python
Domain
testing
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.