{"record":{"id":"6ef0c3b5d803052f","repo":"testcontainers/testcontainers-java","slug":"is-not-a-network-alias-for-k3s-container","errorCode":null,"errorMessage":"{} is not a network alias for k3s container","messagePattern":"(.+?) is not a network alias for k3s container","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/k3s/src/main/java/org/testcontainers/k3s/K3sContainer.java","lineNumber":85,"sourceCode":"     */\n    public String getKubeConfigYaml() {\n        return kubeConfigYaml;\n    }\n\n    /**\n     * Generate a kubernetes client configuration for use on a docker internal network. The kubeConfig can be used by\n     * another docker container running in the same network as the k3s container. For access from the host, use\n     * the {@link #getKubeConfigYaml()} method instead.\n     *\n     * @param networkAlias a valid network alias of the k3s container.\n     * @return the kubeConfig yaml.\n     */\n    public String generateInternalKubeConfigYaml(String networkAlias) {\n        if (this.getNetworkAliases().contains(networkAlias)) {\n            String serverUrl = \"https://\" + networkAlias + \":\" + KUBE_SECURE_PORT;\n            return kubeConfigWithServerUrl(kubeConfigYaml, serverUrl);\n        } else {\n            throw new IllegalArgumentException(networkAlias + \" is not a network alias for k3s container\");\n        }\n    }\n\n    @SneakyThrows\n    private String kubeConfigWithServerUrl(String kubeConfigYaml, String serverUrl) {\n        ObjectMapper objectMapper = new ObjectMapper(new YAMLFactory());\n\n        ObjectNode kubeConfigObjectNode = objectMapper.readValue(kubeConfigYaml, ObjectNode.class);\n\n        JsonNode clusterNode = kubeConfigObjectNode.at(\"/clusters/0/cluster\");\n        if (!clusterNode.isObject()) {\n            throw new IllegalStateException(\"'/clusters/0/cluster' expected to be an object\");\n        }\n        ObjectNode clusterConfig = (ObjectNode) clusterNode;\n        clusterConfig.replace(\"server\", new TextNode(serverUrl));\n\n        kubeConfigObjectNode.set(\"current-context\", new TextNode(\"default\"));\n","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/k3s/src/main/java/org/testcontainers/k3s/K3sContainer.java#L67-L103","documentation":"K3sContainer.generateInternalKubeConfigYaml(networkAlias) builds a kubeconfig whose API server URL points at the given network alias, which only works if that alias is actually registered as a Docker network alias on the k3s container. If the provided name is not among getNetworkAliases(), the generated kubeconfig would point at an unreachable server, so the method fails fast with IllegalArgumentException.","triggerScenarios":"Calling k3sContainer.generateInternalKubeConfigYaml(\"my-k3s\") when 'my-k3s' was never added via withNetworkAliases(...) on a shared network, or the container was not started with any custom network aliases at all.","commonSituations":"Joining the k3s container to a Docker network but forgetting withNetworkAliases; misspelling the alias; calling generateInternalKubeConfigYaml from the host where the alias only resolves inside the network; creating the container via a definition/def API that drops the alias.","solutions":["Add the alias before starting: k3s.withNetwork(network).withNetworkAliases(\"my-k3s\")","Use the exact alias string passed to withNetworkAliases when calling generateInternalKubeConfigYaml","Verify with container.getNetworkAliases() which aliases are actually registered"],"exampleFix":"// before\nK3sContainer k3s = new K3sContainer(DockerImageName.parse(\"rancher/k3s:v1.20.4-k3s1\"));\nString yaml = k3s.generateInternalKubeConfigYaml(\"k3s\");\n\n// after\nK3sContainer k3s = new K3sContainer(DockerImageName.parse(\"rancher/k3s:v1.20.4-k3s1\"))\n    .withNetwork(network)\n    .withNetworkAliases(\"k3s\");\nString yaml = k3s.generateInternalKubeConfigYaml(\"k3s\");","handlingStrategy":"validation","validationCode":"if (!k3s.getNetworkAliases().contains(alias)) {\n  throw new IllegalArgumentException(alias + \" must be added via withNetworkAliases() before calling generateInternalKubeConfigYaml\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  String yaml = k3s.generateInternalKubeConfigYaml(alias);\n} catch (IllegalArgumentException e) {\n  // fall back to default alias or log the available getNetworkAliases()\n}","preventionTips":["Always pair withNetwork(network) with withNetworkAliases(...)","Extract the alias string into a constant reused in both withNetworkAliases and generateInternalKubeConfigYaml","Remember the alias resolves inside the Docker network, not from the host","Assert container.getNetworkAliases() in test setup"],"tags":["k3s","docker-network","kubeconfig"],"backgroundTag":"invalid-argument-value","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"}