Diag: agent wont start, read the parse error, bisect the last edit

TL;DR

Check for two installs: package + manual binary both trying to bind. ss -ltnp shows who holds the agent ports.

Steps

1. Symptom (exact): systemctl start datadog-agent exits non-zero, or the container crash-loops. agent status never runs.
2. Likely causes: (a) yaml syntax error from a recent edit, (b) invalid option value (typo in a boolean, wrong type), (c) permissions on the config or log dirs, (d) port conflict from a second install.
3. Read the agent log from the failed start. The first error is usually a yaml parse error with a line number, or an unknown/invalid option name.
4. Validate the yaml with a parser (python yaml safe_load, or yamllint). Fix the reported line.
5. git diff the config if it is managed (it should be). The last change is the suspect; revert it and start.
6. Check for two installs: package + manual binary both trying to bind. ss -ltnp shows who holds the agent ports.
7. Fix: correct the yaml, fix ownership/perms on /etc/datadog-agent and the log dir, remove the duplicate install, start once.
8. Verify: the service stays up for 5 minutes (crash loops hide behind restart delays), agent status runs clean, forwarder accepts payloads. Then commit the fixed config so the next edit starts from known-good.

When to use

You are seeing this: Symptom (exact): systemctl start datadog-agent exits non-zero, or the container crash-loops. agent status never runs. Use this skill when you run into "Diag: agent wont start, read the parse error, bisect the last edit".

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.

The agent configuration docs define datadog.yaml as the main config with example files per OS in the datadog-agent repo; a bad edit fails validation at startup. Verified against live docs 2026-09-26.