A failed security check should say which rule failed, where, why it matters, how to fix it and how to ask for an exception, in plain language. DORA's 2025 data found that clear feedback on the outcome of tasks was the platform capability most correlated with a positive user experience.
Why the message matters
A paved road lives or dies on the moment a check fails. If the message is a wall of text or a bare error code, the developer opens a ticket, asks in chat, or disables the check. If it is clear, they fix the issue and move on.
DORA's platform engineering guidance says developers need to understand what is happening when they use the platform, especially when something fails, and that clear, actionable feedback, logs and diagnostics let them self serve and troubleshoot independently.
The seven parts of a good failure message
| Part | Example |
|---|---|
| 1. Rule name | Dependency policy: blocked severity |
| 2. What was found | Package name, version and the advisory that applies |
| 3. Where | File and line, or the dependency path that brought it in |
| 4. Why it matters | One sentence on the risk, not a lecture |
| 5. How to fix | The version to move to, or the config line to change |
| 6. What to do if you cannot | A link to the exception route |
| 7. Who to ask | A channel or owner |
If you can add two, add the fix and the exception route. Those two answer the questions a developer asks first.
Before and after
A weak message:
Policy check failed (code 17).
A stronger one:
Blocked by dependency policy: severity gate.
Found: example-lib 2.3.1 (advisory linked below), reached through app-core.
Why: a known vulnerability affects a function your code calls.
Fix: update example-lib to 2.3.4 or later.
Cannot update now? Request a time limited exception: link.
Questions: the platform channel.
The second takes longer to write once, and saves a conversation every time it appears.
Design rules
- Lead with what to do. Put the fix before the explanation.
- Use the developer's words. Name files and packages they recognise.
- Link, do not paste. Keep the message short and link to details.
- Say when it is safe to ignore. If a result is informational, mark it as not blocking.
- Make the same failure look the same. Consistent wording builds trust.
- Test messages with a developer. Ask someone to fix a failure using just the message.
Do not forget the fix path
Failures that come with a ready fix are the easiest for developers to accept. The demo below shows the idea: a finding with a fix available, so the next action is a click rather than research.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how much a developer needs to know to act on the finding.
Where Safeguard fits
Safeguard's gates report findings in pull requests, and its autonomous remediation can propose fix pull requests, which is off by default with every category on Manual until you turn it on. You can try a free scan at gold.safeguard.sh/scan.
Quick check
How long should a failure message be?
Short enough to read at a glance, usually under ten lines, with links for detail. The fix and the exception route should be visible without scrolling.
Should a message name the person who owns the rule?
Name a team channel rather than a person. People move on, channels stay.
Sources
Last reviewed: 19 October 2026.
