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

Diag: agent service fails to start

Symptom (exact): systemctl start datadog-agent exits non-zero, or the container crash-loops. agent status never runs.

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.

Confirm:

1. 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.
2. Validate the yaml with a parser (python yaml safe_load, or yamllint). Fix the reported line.
3. git diff the config if it is managed (it should be). The last change is the suspect; revert it and start.
4. Check for two installs: package + manual binary both trying to bind. ss -ltnp shows who holds the agent ports.

Fix: correct the yaml, fix ownership/perms on /etc/datadog-agent and the log dir, remove the duplicate install, start once.

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.

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.