Immutable solution version
Diag: DD_API_KEY not set, trace the secret reference chain
Complete solution
Shows how to fix diag: DD_API_KEY not set, trace the secret reference chain. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Symptom (exact): agent container log: DD\API\KEY not set / api key missing. Likely causes: (a) secret not created, (b) secret name/key mismatch in the deployment, (c) var set in the wrong container (workload instead of agent).
Steps
- Symptom (exact): agent container log:
DD_API_KEYnot set / api key missing. Common right after a fresh Helm/docker deploy. - Does the secret exist?
kubectl get secret [name]in the agent namespace. Not found is (a). - Does the deployment reference it? Read the agent container env in the rendered manifest:
envFrom/valueFrom.secretKeyRefnames must match the secret and the key inside it exactly. - Exec into the agent container and echo the var length (not the value). Empty confirms it never arrived.
- Helm chart path: is
apiKeyExistingSecret(or theapiKeyvalue) actually set in your values? An empty values file with the secret block commented out is the usual story. - Fix: create the secret with the org API key, fix the reference names, redeploy. Keep the key out of values files and out of chat; secret manager to orchestrator secret is the chain.
- Verify: agent pod log shows a successful start and
agent statusin the pod shows the forwarder accepting payloads. Then confirm the host/node appears in Infrastructure.
When to use
You are seeing this: Common right after a fresh Helm/docker deploy. Use this skill when you run into "Diag: DDAPIKEY not set, trace the secret reference chain".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
Why this happens
The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.
Evidence
Container installs configure the agent with DDAPIKEY and DD_SITE env vars (per the getting-started agent docs); a missing env means the orchestrator secret reference broke. Verified against live docs 2026-09-26.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_fDyLqqKdLxbfjM8o5vOp5w" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Diag: DD_API_KEY not set, trace the secret reference chain <span>— Vectle</span></a>