{"record":{"id":"fd08274ae9ccf2b8","repo":"elastic/elasticsearch","slug":"unable-to-start-apm-server","errorCode":null,"errorMessage":"Unable to start APM server: {}","messagePattern":"Unable to start APM server: (.+?)","errorType":"exception","errorClass":"GradleException","httpStatus":null,"severity":"error","filePath":"build-tools/src/main/java/org/elasticsearch/gradle/testclusters/RunTask.java","lineNumber":285,"sourceCode":"        if (nodeCount != null) {\n            for (ElasticsearchCluster cluster : getClusters()) {\n                cluster.setNumberOfNodes(nodeCount);\n            }\n        }\n        boolean singleNode = getClusters().stream().mapToLong(c -> c.getNodes().size()).sum() == 1;\n        final Function<ElasticsearchNode, Path> getDataPath;\n        if (singleNode) {\n            getDataPath = n -> dataDir;\n        } else {\n            getDataPath = n -> dataDir.resolve(n.getName());\n        }\n\n        if (apmServerEnabled) {\n            try {\n                mockServer = new MockApmServer(apmServerMetrics, apmServerTransactions, apmServerTransactionsExcludes);\n                mockServer.start();\n            } catch (IOException e) {\n                throw new GradleException(\"Unable to start APM server: \" + e.getMessage(), e);\n            }\n        }\n\n        for (ElasticsearchCluster cluster : getClusters()) {\n            cluster.setPreserveDataDir(preserveData);\n            for (ElasticsearchNode node : cluster.getNodes()) {\n                node.setHttpPort(String.valueOf(httpPort++));\n                node.setTransportPort(String.valueOf(transportPort++));\n                additionalSettings.forEach(node::setting);\n                if (dataDir != null) {\n                    node.setDataPath(getDataPath.apply(node));\n                }\n                if (keystorePassword.length() > 0) {\n                    node.keystorePassword(keystorePassword);\n                }\n                if (useHttps) {\n                    validateHelperOption(\"--https\", \"xpack.security.http.ssl\", node);\n                    node.setting(\"xpack.security.http.ssl.enabled\", \"true\");","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools/src/main/java/org/elasticsearch/gradle/testclusters/RunTask.java#L267-L303","documentation":"Thrown by RunTask when MockApmServer.start() raises an IOException while apmServerEnabled is true. The exception is rethrown as a GradleException with the original IOException's message and cause. Note: only e.getMessage() is included — if the IOException has no message the string is empty/null and the cause carries the real detail.","triggerScenarios":"MockApmServer.start() throws IOException from HttpServer.create(new InetSocketAddress(\"0.0.0.0\", 0), 10) — typically because the socket could not be bound (the OS chose port 0, so binding failures are rare unless the ephemeral range is exhausted or a security manager blocks it), or from ServerBuilder.forPort(0).start() for the gRPC server (e.g. native transport unavailable).","commonSituations":"Ephemeral port exhaustion on a heavily loaded CI host; a security manager / SELinux policy denying bind; gRPC native transport loading failure; running on a host where 0.0.0.0 bind is disallowed in a container with restricted net caps.","solutions":["Read the wrapped IOException's cause for the bind/grpc failure detail (the top-level message may be empty).","If ephemeral ports are exhausted, reduce concurrent testclusters / raise net.ipv4.ip_local_port_range.","Disable gRPC native transport if the failure is native-lib loading: set -Dio.grpc.netty.useNativeTransport=false in the gradle JVM.","If you do not need APM, set apmServerEnabled = false on the RunTask to bypass this code path entirely."],"exampleFix":"// before:\nrunTask.apmServerEnabled = true  // fails on this host\n// after (if APM unused):\nrunTask.apmServerEnabled = false","handlingStrategy":"try-catch","validationCode":"// probe bind capability cheaply before real start\ntry (ServerSocket probe = new ServerSocket()) {\n    probe.bind(new InetSocketAddress(\"0.0.0.0\", 0));\n} catch (IOException e) {\n    throw new GradleException(\"Host cannot bind 0.0.0.0:0 — APM mock will fail\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    mockServer = new MockApmServer(...);\n    mockServer.start();\n} catch (IOException e) {\n    throw new GradleException(\"Unable to start APM server: \" + e.getMessage(), e);\n}","preventionTips":["If APM is not needed, set apmServerEnabled=false on the RunTask.","On loaded CI hosts, raise the ephemeral port range or reduce concurrency.","Inspect the wrapped IOException cause — the top-level message may be null."],"tags":["testclusters","apm","run-task","network-bind"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:17:08.281Z"}