{"record":{"id":"185c3927b73b2808","repo":"elastic/elasticsearch","slug":"configuration-qualifiedkey-is-either-prohibite","errorCode":null,"errorMessage":"Configuration [{qualifiedKey}] is either prohibited or unknown.","messagePattern":"Configuration \\[(.+?)\\] is either prohibited or unknown\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/apm/src/main/java/org/elasticsearch/telemetry/apm/internal/APMAgentSetting.java","lineNumber":266,"sourceCode":null,"sourceCodeStart":null,"sourceCodeEnd":null,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/apm/src/main/java/org/elasticsearch/telemetry/apm/internal/APMAgentSetting.java#L266","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the dedicated ES aliases: telemetry.secret_token, telemetry.api_key, telemetry.metrics.enabled, telemetry.tracing.enabled — not the telemetry.agent.* versions.","Cross-check the key against APMAgentSettings.PERMITTED_AGENT_KEYS (the public Set in the source) before using it.","If you genuinely need a key not on the list, file a change request — do not try to bypass the validator.","Remove any global_labels.<x> leftovers from older flattened configs (they are tolerated but inert)."],"exampleFix":"// before\ntelemetry.agent.api_key: \"foo\"\ntelemetry.agent.enabled: true\n// after\ntelemetry.api_key: \"foo\"\ntelemetry.tracing.enabled: true\ntelemetry.metrics.enabled: true","handlingStrategy":"validation","validationCode":"// Validate against the public allowlist before applying telemetry.agent.* keys\nstatic final Set<String> PERMITTED = org.elasticsearch.telemetry.apm.internal.APMAgentSettings.PERMITTED_AGENT_KEYS;\nstatic List<String> rejectUnknown(String prefix, Map<String,Object> userSettings) {\n  return userSettings.keySet().stream()\n    .filter(k -> k.startsWith(prefix))\n    .map(k -> k.substring(prefix.length()))\n    .filter(ns -> !PERMITTED.contains(ns) && !ns.startsWith(\"global_labels.\"))\n    .toList();\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer the dedicated telemetry.* aliases (telemetry.api_key, telemetry.secret_token, telemetry.tracing.enabled, telemetry.metrics.enabled).","Cross-check any telemetry.agent.* key against PERMITTED_AGENT_KEYS in the source.","Lint elasticsearch.yml in CI against the allowlist."],"tags":["apm","telemetry","configuration","validation","allowlist"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}