{"record":{"id":"f77b0e73851f5834","repo":"testcontainers/testcontainers-java","slug":"could-not-connect-to-ryuk-at-s-s","errorCode":null,"errorMessage":"Could not connect to Ryuk at %s:%s","messagePattern":"Could not connect to Ryuk at (.+?):(.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/testcontainers/utility/RyukResourceReaper.java","lineNumber":132,"sourceCode":"                                    } else {\n                                        log.debug(\"Didn't receive 'ACK' from Ryuk. Will retry to send filters.\");\n                                    }\n                                }\n                            }\n                        } catch (IOException e) {\n                            log.warn(\"Can not connect to Ryuk at {}:{}\", host, ryukPort, e);\n                        }\n                    });\n                }\n            },\n            \"testcontainers-ryuk\"\n        );\n        kiraThread.setDaemon(true);\n        kiraThread.start();\n        // We need to wait before we can start any containers to make sure that we delete them\n        if (!ryukScheduledLatch.await(TestcontainersConfiguration.getInstance().getRyukTimeout(), TimeUnit.SECONDS)) {\n            log.error(\"Timed out waiting for Ryuk container to start. Ryuk's logs:\\n{}\", ryukContainer.getLogs());\n            throw new IllegalStateException(String.format(\"Could not connect to Ryuk at %s:%s\", host, ryukPort));\n        }\n    }\n}\n","sourceCodeStart":114,"sourceCodeEnd":136,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/utility/RyukResourceReaper.java#L114-L136","documentation":"Ryuk is Testcontainers' sidecar container that reaps orphaned containers/networks/volumes after the JVM exits. In RyukResourceReaper.maybeStart the client thread signals readiness via ryukScheduledLatch; if the latch is not counted down within ryuk.timeout seconds, Testcontainers concludes the Ryuk container never became reachable and throws this IllegalStateException, failing container startup.","triggerScenarios":"Starting any container when Ryuk is enabled and: the Ryuk image cannot be pulled (offline/private registry), the host port for Ryuk is not reachable (firewall, remote Docker host without exposed port), Ryuk fails to boot (incompatible image/arch), or the configured timeout is too short.","commonSituations":"CI runners with restrictive networking to remote Docker (DOCKER_HOST over ssh/tcp); air-gapped environments without the testcontainers/ryuk image in a local mirror; enterprise proxies blocking the connection; slow image pulls exceeding the default timeout.","solutions":["Verify the Ryuk image (testcontainers/ryuk:*) can be pulled: docker pull it manually / configure a registry mirror","If Ryuk cannot run in your environment, set TESTCONTAINERS_RYUK_DISABLED=true (in ~/.testcontainers.properties) — you then own cleanup of stopped containers","Increase the wait via testcontainers.properties `ryuk.timeout` or env TESTCONTAINERS_RYUK_TIMEOUT","Check network reachability from the JVM to the Docker host/port (firewall, DOCKER_HOST misconfiguration, proxy settings)"],"exampleFix":"// before\n// tests fail: Could not connect to Ryuk at 172.17.0.1:32768\n// after (testcontainers.properties)\nryuk.disabled=true\n// or\nryuk.timeout=120","handlingStrategy":"retry","validationCode":"// before tests: verify Ryuk image is pullable and Docker host reachable\ndocker pull testcontainers/ryuk:0.11.0\nnc -z <docker-host> <port> || echo \"Ryuk port unreachable\"","typeGuard":null,"tryCatchPattern":"try {\n    container.start();\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Could not connect to Ryuk\")) {\n        log.warn(\"Ryuk unavailable; disabling and retrying\", e);\n        // restart with ryuk.disabled=true in testcontainers.properties\n    } else throw e;\n}","preventionTips":["Pre-pull the Ryuk image in CI and configure registry mirrors for air-gapped environments","Increase ryuk.timeout for slow image pulls","Disable Ryuk on remote/restricted Docker hosts and handle cleanup yourself","Check firewall/proxy rules between JVM and Docker host"],"tags":["ryuk","timeout","network","docker","resource-cleanup"],"backgroundTag":"request-timeout","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}