Skip to main content

​
Overview

Incident Causes are the shared vocabulary your team uses to describe why an incident happened. Where Severity captures how bad an incident was and Types captures what category it fell into, Causes capture the underlying failure mode — Third-party outage, Configuration drift, Deployment regression, Insufficient monitoring. Causes are the field most retrospectives circle back to. Their real value shows up over the long term: three months of tagged Causes reveals whether your team is losing time to the same failure modes repeatedly, and gives reliability planning something concrete to point at.
Incident Causes configuration

​
How Incident Causes Are Used

Unlike Severity or Environment (set at incident creation), Causes are typically populated during the retrospective process — after mitigation, when the responding team has enough evidence to say what actually went wrong. The field is a multi-select because most real incidents have more than one contributing cause. Because Causes are the primary input to reliability planning, the shape of your Cause list directly shapes what your team can improve on. An overly generic list (Bug, Human Error) hides the actual failure modes; an overly granular one (OAuth expiry on service X) splinters data across too many buckets to see patterns.

​
Choosing Your Cause Taxonomy

Causes should describe failure modes, not incidents. The distinction matters — “Payment API returned 500s” is an incident description; Third-party outage and Insufficient retry logic are causes.

​
How Many Causes

Most teams land on 8–15 causes. Fewer and everything collapses into Other. More and the causes stop being meaningfully different — responders default to the top-of-picker choices, and metrics lose signal. If a Cause hasn’t been used in 90 days, retire it. If a single Cause accounts for more than 25% of incidents over 90 days, it’s probably too broad and needs to be split.

​
Common Cause Categories

Causes that describe how systems broke, regardless of what the trigger was.
Causes that describe what your team could have done differently before the incident.
Causes that describe factors outside the team’s direct control.

​
Creating Incident Causes

Manage Causes from Configuration → Incident Causes in the Rootly dashboard sidebar. (The Catalogs section is for service/component catalogs from tools like Backstage and Cortex — it does not create incident causes.)
1

Open Configuration → Incident Causes

In the Rootly sidebar, navigate to Configuration → Incident Causes. The page lists every cause already defined for your organization.
2

Add A New Cause

Click Add New (or the equivalent create button at the top of the list). Fill in:
  • Name — the display label that responders see on the incident form (e.g., Database deadlock, Third-party outage, Deployment regression).
  • Description — optional context shown when the cause is selected. Best used to disambiguate similar-sounding causes.
  • Color — optional visual tag for dashboards and reports.
The Slug is generated automatically from the Name by lower-casing and hyphenating — used in Liquid references and the API.
3

Save

Click Save. The new cause becomes immediately available as an option on the incident form’s Causes multi-select field for all team members.
Causes are multi-select per incident — responders can attach more than one cause when the root cause is genuinely shared between failure modes (e.g., Third-party outage and Insufficient monitoring). Keep the list short and orthogonal to encourage selection rather than freeform notes.

​
Field Type

Incident Causes is a multi-select field type only. Every incident can have zero, one, or many causes attached — reflecting the reality that most incidents have multiple contributing factors.

​
Configuring Cause Attributes

Each Cause can be configured with the attributes below. All are available in Liquid syntax for use in workflows, retrospective templates, and status page updates.
​
ID
string
required
Unique identifier assigned automatically by Rootly on creation. Not customizable. Used in Liquid references and API calls.
​
Name
string
required
The display name shown throughout the Rootly UI. Fully customizable — pick names that describe failure modes, not incident descriptions.
​
Slug
string
required
Auto-generated by lower-casing and hyphenating the name. Used in Liquid references and stable across name changes.
​
Description
string
Additional context shown alongside the Cause in the UI. Best used to disambiguate similar-sounding Causes — e.g., “Third-party outage: use when the external service itself is down. Use Vendor incident for cases where the vendor is up but their code introduced a bug in your system.”
​
Color
string (hex)
Six-digit hex color code used for Cause-tinted UI accents and metrics-graph color coding. Group related causes with similar shades (e.g., all “system” causes in blue, all “process” causes in orange).
Rootly expects six-digit hex codes (e.g., #c4231c). Use a color picker if you’re not sure — color-hex.com is a common choice.
Iterating over all Causes on an incident (for a Liquid template in a retrospective or workflow message):

​
Best Practices

  • Populate Causes during the retrospective, not at incident creation. At creation time you don’t know what caused the incident — you know a symptom. Wait until mitigation is done and the responding team has enough evidence to attach real causes.
  • Design Causes to describe failure modes. Payment API returned 500s is an incident description; Third-party outage and Insufficient retry logic are causes. The rewrite test: if the Cause could describe two different incidents in the same category, it’s a good failure-mode Cause.
  • Encourage multi-select. Most real incidents have more than one cause. A single-cause tagging pattern usually means responders are collapsing complex root causes into whichever tag is dominant, which loses signal.
  • Keep the list short and orthogonal. Aim for 8–15 causes. If two Causes overlap conceptually (e.g., Deploy failure and Deployment regression), merge them. If a Cause hasn’t been used in 90 days, archive it.
  • Retire and split based on data. Every quarter, look at Cause frequency. Rare Causes (<5% of incidents) get archived; dominant Causes (>25% of incidents) get split into more specific failure modes.
  • Pair Causes with action items. Cause tagging without follow-up work isn’t reliability improvement — it’s data collection. Each recurring Cause should have at least one open action item aimed at reducing its frequency.

​
Troubleshooting

Confirm the Cause is enabled under Configuration → Incident Causes. Archived Causes remain visible on historical incidents but don’t appear as options on new incidents. Also check whether team-level restrictions are in play — some teams scope which Causes their responders can select.
Two common causes: (1) responders are defaulting to a single Cause because the list is too long or badly ordered — reorder so most-common Causes are at the top; (2) responders aren’t populating Causes at all because the field isn’t on the retrospective flow. Add the Causes field to the Incident Retrospective Form so it appears in the Gather & Confirm Data step.
Metrics queries filter by the Cause slug, not name. Renaming a Cause keeps the slug stable, so historical incidents remain grouped correctly. If a report is grouping incorrectly after a rename, refresh the dashboard cache — some reports lag one query cycle after configuration changes.
The workflow’s trigger needs to be Causes Added (or Causes Updated), and the run conditions need to reference the specific Cause you’re tagging. See Workflow Conditions for the operator reference — Causes is a multi-select field, so use contains any of, not is.
They shouldn’t. Deleting a Cause keeps the historical association intact on incidents that had it tagged; the Cause name just won’t render on the current UI (it appears as archived). If you’re seeing Causes disappear entirely from historical incidents, contact support — that’s not expected behavior.

​
Frequently Asked Questions

Type captures what kind of thing the incident is — UI Bug, Infrastructure, Security Event. Cause captures why the incident happened — Third-party outage, Configuration drift, Insufficient monitoring. Type is usually set at incident creation; Cause is usually set during the retrospective. See Incident Types for the Type reference.
After. During an active incident, responders don’t yet know what caused the issue — they know symptoms. Wait until mitigation is done and the responding team has enough evidence. Most teams populate Causes as part of the retrospective template.
Most teams land on 8–15. Fewer and everything collapses into Other. More and the causes stop being meaningfully different in practice. Audit quarterly and archive rare Causes (<5% usage).
Yes. Causes can be added programmatically via the incident update API and by workflow actions (Update Incident action → set Causes). This is useful for auto-tagging based on integration data — e.g., automatically add Third-party outage when a specific external monitor triggered the incident.
The Causes list is org-wide, but teams can restrict which Causes their responders can select. A shared Cause list with team-specific defaults is usually cleaner than maintaining separate lists per team.
No. Test incidents (declared via /rootly test) are excluded from production metrics regardless of Cause. This is a Kind-level behavior; see Incident Kind for the full exclusion matrix.
Yes. Add the Causes field to the Incident Retrospective Form and mark it required. Since the form runs during the Gather & Confirm Data step, the retrospective can’t advance past that step without at least one Cause selected.

Collaborative Retrospectives

Where most Causes get populated. The retrospective template is your primary Cause-collection surface.

Workflow Conditions

Use Causes in workflow conditions to trigger auto-responses (add responder team, spawn action items) when specific failure modes are tagged.

Incident Types

The what-kind-of-incident field, distinct from Cause (why-it-happened). Read this to disambiguate the two.