{"record":{"id":"76684010bff8cba9","repo":"pinpoint-apm/pinpoint","slug":"no-per-instance-identifier-set-service-instance","errorCode":null,"errorMessage":"no per-instance identifier — set service.instance.id (e.g. via uuidgen), k8s.pod.uid, container.id, or host.name. applicationName='${applicationName}'","messagePattern":"no per-instance identifier — set service\\.instance\\.id \\(e\\.g\\. via uuidgen\\), k8s\\.pod\\.uid, container\\.id, or host\\.name\\. applicationName='(.+?)'","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"otlptrace/otlptrace-collector/src/main/java/com/navercorp/pinpoint/otlp/trace/collector/mapper/OtlpTraceMapperUtils.java","lineNumber":181,"sourceCode":"        }\n\n        final String containerId = AttributeUtils.getAttributeStringValue(attributes, KEY_CONTAINER_ID, null);\n        if (containerId != null) {\n            return toContainerAgentAuth(containerId, agentNameOverride);\n        }\n\n        final String hostName = AttributeUtils.getAttributeStringValue(attributes, KEY_HOST_NAME, null);\n        if (hostName != null) {\n            if (!IdValidateUtils.validateId(hostName, PinpointConstants.AGENT_ID_MAX_LEN)) {\n                throw new IllegalArgumentException(\"invalid host.name=\" + hostName);\n            }\n            return new AgentAuth(hostName, resolveAgentName(agentNameOverride, hostName));\n        }\n\n        // applicationName fallback — test/dev environment only.\n        // Gated by pinpoint.collector.otlptrace.application-name-fallback.enabled (default: false).\n        if (!allowApplicationNameFallback) {\n            throw new IllegalArgumentException(\"no per-instance identifier — set service.instance.id (e.g. via uuidgen), k8s.pod.uid, container.id, or host.name. applicationName='\" + applicationName + \"'\");\n        }\n        if (!IdValidateUtils.validateId(applicationName, PinpointConstants.AGENT_ID_MAX_LEN)) {\n            throw new IllegalArgumentException(\"invalid agentId(derived from applicationName)=\" + applicationName);\n        }\n        return new AgentAuth(applicationName, resolveAgentName(agentNameOverride, applicationName));\n    }\n\n    private static AgentAuth toAgentAuth(String id, String sourceKey, String agentNameOverride) {\n        if (id.length() == 36) {\n            try {\n                final UUID uuid = UUID.fromString(id);\n                return new AgentAuth(Base64Utils.encode(uuid), resolveAgentName(agentNameOverride, id));\n            } catch (IllegalArgumentException ignore) {\n                // not a valid UUID string, fall through to treat as plain agentId\n            }\n        }\n        if (!IdValidateUtils.validateId(id, PinpointConstants.AGENT_ID_MAX_LEN)) {\n            throw new IllegalArgumentException(\"invalid \" + sourceKey + \"=\" + id);","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/otlptrace/otlptrace-collector/src/main/java/com/navercorp/pinpoint/otlp/trace/collector/mapper/OtlpTraceMapperUtils.java#L163-L199","documentation":"getAgentAuth requires SOME per-instance identifier (service.instance.id, k8s pod uid, container id, host.name, or agentId) to build an AgentAuth. When none is present, it cannot distinguish instances and throws — unless the (disabled-by-default) applicationName fallback is explicitly enabled via pinpoint.collector.otlptrace.application-name-fallback.enabled.","triggerScenarios":"OTLP span attributes contain none of KEY_AGENT_ID, KEY_SERVICE_INSTANCE_ID, pod-uid, container-id, KEY_HOST_NAME, and allowApplicationNameFallback is false (the default) at mapping time.","commonSituations":"Bare OTLP exporters (e.g. local dev scripts, libraries with default resource) that only set service.name; K8s pods without the downgraded pod-uid resource attribute; collector config where the fallback flag was left disabled.","solutions":["Set service.instance.id, e.g. OTEL_RESOURCE_ATTRIBUTES=service.instance.id=$(uuidgen)","On Kubernetes, ensure k8s.pod.uid is attached via the resource detector","Enable the collector's application-name fallback only for test/dev: set pinpoint.collector.otlptrace.application-name-fallback.enabled=true","Add host.name or container.id resource attributes so a per-instance id exists"],"exampleFix":"// before\n// (no instance-level resource attributes)\n// after\nexport OTEL_RESOURCE_ATTRIBUTES=service.instance.id=$(uuidgen),service.name=my-app","handlingStrategy":"validation","validationCode":"boolean hasId = Stream.of(KEY_AGENT_ID, KEY_SERVICE_INSTANCE_ID, KEY_HOST_NAME, \"container.id\", \"k8s.pod.uid\")\n    .anyMatch(k -> AttributeUtils.getAttributeStringValue(attributes, k, null) != null);\nif (!hasId) throw new IllegalStateException(\"no per-instance identifier in OTLP attributes\");","typeGuard":null,"tryCatchPattern":"try { AgentAuth a = getAgentAuth(attrs, override, app, false); } catch (IllegalArgumentException e) { log.error(\"OTLP span missing instance identifier: {}\", e.getMessage()); }","preventionTips":["Set service.instance.id=$(uuidgen) on every exporter","Enable k8s resource detection for pod.uid in Kubernetes","Only enable the applicationName fallback flag in test/dev"],"tags":["otlp","missing-attribute","identity"],"backgroundTag":"missing-required-argument","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}