{"record":{"id":"b554c060e9acf48c","repo":"testcontainers/testcontainers-java","slug":"cannot-obtain-endpoint-url-localstackcontainer","errorCode":null,"errorMessage":"Cannot obtain endpoint URL","messagePattern":"Cannot obtain endpoint URL","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"modules/localstack/src/main/java/org/testcontainers/localstack/LocalStackContainer.java","lineNumber":161,"sourceCode":"             localstack.getAccessKey(), localstack.getSecretKey()\n             )))\n             .region(Region.of(localstack.getRegion()))\n             .build()\n             </code></pre>\n     * <p><strong>Please note that this method is only intended to be used for configuring AWS SDK clients\n     * that are running on the test host. If other containers need to call this one, they should be configured\n     * specifically to do so using a Docker network and appropriate addressing.</strong></p>\n     *\n     * @return an {@link URI} endpoint\n     */\n    public URI getEndpoint() {\n        try {\n            final String address = getHost();\n            // resolve IP address and use that as the endpoint so that path-style access is automatically used for S3\n            String ipAddress = InetAddress.getByName(address).getHostAddress();\n            return new URI(\"http://\" + ipAddress + \":\" + getMappedPort(PORT));\n        } catch (UnknownHostException | URISyntaxException e) {\n            throw new IllegalStateException(\"Cannot obtain endpoint URL\", e);\n        }\n    }\n\n    /**\n     * Provides a default access key that is preconfigured to communicate with a given simulated service.\n     * <a href=\"https://github.com/localstack/localstack/blob/master/doc/interaction/README.md?plain=1#L32\">AWS Access Key</a>\n     * The access key can be used to construct AWS SDK v2 clients:\n     * <pre><code>S3Client s3 = S3Client\n             .builder()\n             .endpointOverride(localstack.getEndpoint())\n             .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(\n             localstack.getAccessKey(), localstack.getSecretKey()\n             )))\n             .region(Region.of(localstack.getRegion()))\n             .build()\n     </code></pre>\n     * @return a default access key\n     */","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/localstack/src/main/java/org/testcontainers/localstack/LocalStackContainer.java#L143-L179","documentation":"LocalStackContainer.getEndpoint() resolves the container host to an IP address and builds an http:// URI with the mapped port. If DNS resolution of the host fails (UnknownHostException) or the resulting URI is malformed (URISyntaxException), it wraps the cause in this IllegalStateException. It exists so callers get a single clear failure when the LocalStack endpoint cannot be constructed.","triggerScenarios":"Calling getEndpoint() before the container is started (getMappedPort returns nothing meaningful / host unresolvable), or when the Docker host hostname cannot be resolved by InetAddress.getByName (bad docker.host config, DNS issues in the environment, or an unresolvable address from DOCKER_HOST).","commonSituations":"Tests that call getEndpoint() in a @BeforeAll before container.start(); CI environments where the Docker daemon host string (e.g. tcp://some-proxy) is not resolvable; custom DOCKER_HOST settings with odd hostnames; VPN or corporate DNS blocking resolution.","solutions":["Call container.start() before invoking getEndpoint()","Check that your Docker host (DOCKER_HOST / docker context) points to a resolvable hostname; inspect the wrapped UnknownHostException in the exception cause","Fix DNS/hosts resolution for the Docker host (add an /etc/hosts entry or use an IP-based DOCKER_HOST)","If constructing the URI yourself elsewhere, validate the host string before use"],"exampleFix":"// before\nLocalStackContainer container = new LocalStackContainer(DockerImageName.parse(\"localstack/localstack\"));\nURI endpoint = container.getEndpoint(); // IllegalStateException: Cannot obtain endpoint URL\n// after\nLocalStackContainer container = new LocalStackContainer(DockerImageName.parse(\"localstack/localstack\"));\ncontainer.start();\nURI endpoint = container.getEndpoint();","handlingStrategy":"try-catch","validationCode":"if (!container.isRunning()) {\n    throw new IllegalStateException(\"Start the LocalStackContainer before calling getEndpoint()\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    URI endpoint = container.getEndpoint();\n} catch (IllegalStateException e) {\n    throw new AssertionError(\"LocalStack endpoint unavailable: \" + e.getCause(), e);\n}","preventionTips":["Always call start() before any getter that needs the mapped port or host","Pin a resolvable DOCKER_HOST / docker context in CI and dev","Log the cause (UnknownHostException) to distinguish DNS vs lifecycle issues"],"tags":["docker","aws","localstack","network","dns"],"backgroundTag":"invalid-url","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"}