elastic/elasticsearch · error · IllegalArgumentException

Configuration [{qualifiedKey}] is either prohibited or unkno

Error message

Configuration [{qualifiedKey}] is either prohibited or unknown.

What it means

Every 'telemetry.agent.<key>' setting is routed through concreteAgentSetting, which only accepts keys whose namespace appears in the hardcoded PERMITTED_AGENT_KEYS allowlist (or starts with 'global_labels.'). Anything else throws IllegalArgumentException at validation time. Deliberately forbidden keys (secret_token, api_key, enabled, recording, instrument, central_config, config_file, service_version, url_groups, log_file, log_format_sout, log_format_file, enable_experimental_instrumentations) are NOT in the list — they are owned by APMJvmOptions or exposed under dedicated telemetry.* aliases.

Source

Thrown at modules/apm/src/main/java/org/elasticsearch/telemetry/apm/internal/APMAgentSetting.java:266

View on GitHub (pinned to db6a809a66)

Solutions

1. Use the dedicated ES aliases: telemetry.secret_token, telemetry.api_key, telemetry.metrics.enabled, telemetry.tracing.enabled — not the telemetry.agent.* versions.
2. Cross-check the key against APMAgentSettings.PERMITTED_AGENT_KEYS (the public Set in the source) before using it.
3. If you genuinely need a key not on the list, file a change request — do not try to bypass the validator.
4. Remove any global_labels.<x> leftovers from older flattened configs (they are tolerated but inert).

Example fix

// before
telemetry.agent.api_key: "foo"
telemetry.agent.enabled: true
// after
telemetry.api_key: "foo"
telemetry.tracing.enabled: true
telemetry.metrics.enabled: true

// Validate against the public allowlist before applying telemetry.agent.* keys
static final Set<String> PERMITTED = org.elasticsearch.telemetry.apm.internal.APMAgentSettings.PERMITTED_AGENT_KEYS;
static List<String> rejectUnknown(String prefix, Map<String,Object> userSettings) {
  return userSettings.keySet().stream()
    .filter(k -> k.startsWith(prefix))
    .map(k -> k.substring(prefix.length()))
    .filter(ns -> !PERMITTED.contains(ns) && !ns.startsWith("global_labels."))
    .toList();
}

When it happens

Trigger: Setting a forbidden key directly (e.g. telemetry.agent.api_key, telemetry.agent.secret_token, telemetry.agent.enabled, telemetry.agent.recording), or any genuinely unknown telemetry.agent.* key, in elasticsearch.yml or via cluster update settings.

Common situations: Copy-pasting APM Java agent docs into ES telemetry config (the bare agent key names are not accepted here); trying to enable/disable the agent dynamically; configuring auth via the wrong alias.

Related errors

• 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
• {thisSettingKey} ({value}) must be greater than {otherSettin
• Failed to initialise TLS context for OTel log export

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