{"record":{"id":"ecbf88d2e598d7e2","repo":"elastic/elasticsearch","slug":"78-ecbf88","errorCode":"78","errorMessage":"Do not set a value for [telemetry.agent.{key}], as this is configured automatically by Elasticsearch","messagePattern":"Do not set a value for \\[telemetry\\.agent\\.(.+?)\\], as this is configured automatically by Elasticsearch","errorType":"exception","errorClass":"UserException","httpStatus":null,"severity":"error","filePath":"distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/APMJvmOptions.java","lineNumber":272,"sourceCode":"\n    // package private for testing\n    static Map<String, String> extractApmSettings(Settings settings) throws UserException {\n        final Map<String, String> propertiesMap = new HashMap<>();\n\n        final String telemetryAgentPrefix = \"telemetry.agent.\";\n\n        final Settings telemetryAgentSettings = settings.getByPrefix(telemetryAgentPrefix);\n        telemetryAgentSettings.keySet().forEach(key -> propertiesMap.put(key, String.valueOf(telemetryAgentSettings.get(key))));\n\n        StringJoiner globalLabels = extractGlobalLabels(telemetryAgentPrefix, propertiesMap, settings);\n        if (globalLabels.length() > 0) {\n            propertiesMap.put(\"global_labels\", globalLabels.toString());\n        }\n\n        // These settings must not be changed\n        for (String key : STATIC_CONFIG.keySet()) {\n            if (propertiesMap.containsKey(key)) {\n                throw new UserException(\n                    ExitCodes.CONFIG,\n                    \"Do not set a value for [telemetry.agent.\" + key + \"], as this is configured automatically by Elasticsearch\"\n                );\n            }\n        }\n\n        CONFIG_DEFAULTS.forEach(propertiesMap::putIfAbsent);\n\n        propertiesMap.putAll(STATIC_CONFIG);\n        return propertiesMap;\n    }\n\n    /**\n     * Disables the APM Agent hook that adds an exporter to application {@code SdkMeterProvider} instances.\n     * When Elasticsearch uses the OTel SDK for metrics, that hook is redundant and can break export;\n     * traces still use the APM Agent through {@code GlobalOpenTelemetry}.\n     */\n    static void disableMetricInstrumentation(Map<String, String> propertiesMap) {","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/APMJvmOptions.java#L254-L290","documentation":"Thrown by APMJvmOptions.extractApmSettings() when a user explicitly sets one of the reserved telemetry.agent.* keys that Elasticsearch manages internally: service_version, instrument, or enable_experimental_instrumentations. ES auto-configures these (e.g. service_version is set to the ES build version), so manual values would conflict.","triggerScenarios":"Setting any of these in elasticsearch.yml: telemetry.agent.service_version, telemetry.agent.instrument, or telemetry.agent.enable_experimental_instrumentations.","commonSituations":"Copying APM agent docs/examples into ES config; trying to enable auto-instrumentation (ES explicitly disables it); pinning a service_version different from the ES build.","solutions":["Remove the offending telemetry.agent.service_version / .instrument / .enable_experimental_instrumentations line from elasticsearch.yml.","Leave service_version to ES (it uses Build.current().version()).","Do not set telemetry.agent.instrument — ES forces it to false because it does not use auto-instrumentation."],"exampleFix":"# elasticsearch.yml — before\ntelemetry.agent.service_version: \"7.17.0\"\ntelemetry.agent.instrument: true\n\n# after (remove both; ES sets them automatically)\n# (no telemetry.agent.service_version / .instrument entries)","handlingStrategy":"validation","validationCode":"Set<String> reserved = Set.of(\"service_version\", \"instrument\", \"enable_experimental_instrumentations\");\nSettings agent = settings.getByPrefix(\"telemetry.agent.\");\nfor (String k : reserved) {\n    if (agent.keySet().contains(k)) {\n        throw new IllegalArgumentException(\"Remove telemetry.agent.\" + k + \" — ES manages it automatically.\");\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never set telemetry.agent.service_version / .instrument / .enable_experimental_instrumentations.","Only configure non-reserved telemetry.agent.* keys.","Cross-check APM settings against the ES docs reserved-keys list."],"tags":["apm","telemetry","config","reserved-settings"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}