elastic/elasticsearch · error · UserException

78

78

Error message

Do not set a value for [telemetry.agent.{key}], as this is configured automatically by Elasticsearch

What it means

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.

Source

Thrown at distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/APMJvmOptions.java:272

    // package private for testing
    static Map<String, String> extractApmSettings(Settings settings) throws UserException {
        final Map<String, String> propertiesMap = new HashMap<>();

        final String telemetryAgentPrefix = "telemetry.agent.";

        final Settings telemetryAgentSettings = settings.getByPrefix(telemetryAgentPrefix);
        telemetryAgentSettings.keySet().forEach(key -> propertiesMap.put(key, String.valueOf(telemetryAgentSettings.get(key))));

        StringJoiner globalLabels = extractGlobalLabels(telemetryAgentPrefix, propertiesMap, settings);
        if (globalLabels.length() > 0) {
            propertiesMap.put("global_labels", globalLabels.toString());
        }

        // These settings must not be changed
        for (String key : STATIC_CONFIG.keySet()) {
            if (propertiesMap.containsKey(key)) {
                throw new UserException(
                    ExitCodes.CONFIG,
                    "Do not set a value for [telemetry.agent." + key + "], as this is configured automatically by Elasticsearch"
                );
            }
        }

        CONFIG_DEFAULTS.forEach(propertiesMap::putIfAbsent);

        propertiesMap.putAll(STATIC_CONFIG);
        return propertiesMap;
    }

    /**
     * Disables the APM Agent hook that adds an exporter to application {@code SdkMeterProvider} instances.
     * When Elasticsearch uses the OTel SDK for metrics, that hook is redundant and can break export;
     * traces still use the APM Agent through {@code GlobalOpenTelemetry}.
     */
    static void disableMetricInstrumentation(Map<String, String> propertiesMap) {

View on GitHub (pinned to db6a809a66)

Solutions

1. Remove the offending telemetry.agent.service_version / .instrument / .enable_experimental_instrumentations line from elasticsearch.yml.
2. Leave service_version to ES (it uses Build.current().version()).
3. Do not set telemetry.agent.instrument — ES forces it to false because it does not use auto-instrumentation.

Example fix

# elasticsearch.yml — before
telemetry.agent.service_version: "7.17.0"
telemetry.agent.instrument: true

# after (remove both; ES sets them automatically)
# (no telemetry.agent.service_version / .instrument entries)

Set<String> reserved = Set.of("service_version", "instrument", "enable_experimental_instrumentations");
Settings agent = settings.getByPrefix("telemetry.agent.");
for (String k : reserved) {
    if (agent.keySet().contains(k)) {
        throw new IllegalArgumentException("Remove telemetry.agent." + k + " — ES manages it automatically.");
    }
}

When it happens

Trigger: Setting any of these in elasticsearch.yml: telemetry.agent.service_version, telemetry.agent.instrument, or telemetry.agent.enable_experimental_instrumentations.

Common situations: 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.

Related errors

• Configuration [{qualifiedKey}] is either prohibited or unkno
• Failed to initialise TLS context for OTel log export
• telemetry.logs.endpoint must be configured when telemetry.lo
• telemetry.logs.endpoint must be configured when telemetry.lo
• telemetry.logs.ssl.certificate and telemetry.logs.ssl.key mu

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/ecbf88d2e598d7e2. Report an issue: GitHub.