{
  "doc": {
    "id": "accessibility/troubleshooting",
    "title": "Troubleshooting: Cypress Accessibility",
    "description": "Fix common Cypress Accessibility report problems: ignored elements that still appear, scores that do not improve, rules you cannot resolve yet, noise from third-party UI, unstable violation selectors, and configuration that has no effect.",
    "section": "accessibility",
    "source_path": "/llm/markdown/accessibility/troubleshooting.md",
    "version": "fbc9225067c51c52ee13224e3b702cf8a025ec12",
    "updated_at": "2026-08-14T12:36:26.878Z",
    "headings": [
      {
        "id": "accessibility/troubleshooting#troubleshooting-cypress-accessibility",
        "text": "Troubleshooting Cypress Accessibility",
        "level": 1
      },
      {
        "id": "accessibility/troubleshooting#an-element-you-excluded-still-appears-in-the-report",
        "text": "An element you excluded still appears in the report",
        "level": 2
      },
      {
        "id": "accessibility/troubleshooting#your-score-didnt-improve-after-excluding-an-element",
        "text": "Your score didn't improve after excluding an element",
        "level": 2
      },
      {
        "id": "accessibility/troubleshooting#a-rule-keeps-failing-and-you-cant-resolve-it-yet",
        "text": "A rule keeps failing and you can't resolve it yet",
        "level": 2
      },
      {
        "id": "accessibility/troubleshooting#third-party-or-out-of-scope-ui-is-adding-noise",
        "text": "Third-party or out-of-scope UI is adding noise",
        "level": 2
      },
      {
        "id": "accessibility/troubleshooting#violation-selectors-use-unstable-or-unhelpful-identifiers",
        "text": "Violation selectors use unstable or unhelpful identifiers",
        "level": 2
      },
      {
        "id": "accessibility/troubleshooting#a-configuration-rule-has-no-effect",
        "text": "A configuration rule has no effect",
        "level": 2
      },
      {
        "id": "accessibility/troubleshooting#a-profile-isnt-being-applied",
        "text": "A profile isn't being applied",
        "level": 2
      },
      {
        "id": "accessibility/troubleshooting#still-stuck",
        "text": "Still stuck?",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "accessibility/troubleshooting#an-element-you-excluded-still-appears-in-the-report",
      "doc_id": "accessibility/troubleshooting",
      "heading": "An element you excluded still appears in the report",
      "heading_level": 2,
      "content_markdown": "## An element you excluded still appears in the report\n\nYou added an [`elementFilters`](/llm/markdown/accessibility/configuration/elementfilters.md) rule to remove an element, but it's still shown with violations in the report.\n\n**Cause.** The rule was saved after the run was processed, the selector doesn't match the element, or an earlier rule already decided the element's fate. `elementFilters` selectors must match the element that Axe Core® reports, not a wrapper around it, and the **first** matching rule wins.\n\n**Fixes.**\n\n*   **Regenerate the run** so the new rule is applied. This is by far the most common cause.\n    \n*   **Check the selector** against the exact node in the violation's HTML snapshot. A rule like `footer` matches only the `<footer>` element itself, while `footer *` matches the controls inside it.\n    \n*   **Order rules from specific to broad**, and place any `include: true` exception before the `include: false` rule it should override, because the first matching rule wins.\n    \n    App Quality Config\n    \n    ```\n    {  \"elementFilters\": [    {      \"selector\": \".intercom-launcher\",      \"include\": false,      \"comment\": \"Third-party chat widget, not part of our tested UI\"    }  ]}\n    ```\n    \n\nSee [How are elementFilters rules applied?](/llm/markdown/accessibility/configuration/elementfilters.md) for the full precedence rules.\n",
      "section": "accessibility",
      "anchors": [
        "an-element-you-excluded-still-appears-in-the-report"
      ],
      "path": "/llm/json/chunked/accessibility/troubleshooting.json",
      "token_estimate": 249
    },
    {
      "id": "accessibility/troubleshooting#your-score-didnt-improve-after-excluding-an-element",
      "doc_id": "accessibility/troubleshooting",
      "heading": "Your score didn't improve after excluding an element",
      "heading_level": 2,
      "content_markdown": "## Your score didn't improve after excluding an element\n\nYou removed a failing element with [`elementFilters`](/llm/markdown/accessibility/configuration/elementfilters.md), but the [accessibility score](/llm/markdown/accessibility/core-concepts/accessibility-score.md) is unchanged or barely moved.\n\n**Cause.** The score is based on the elements checked and the severity of the rules they fail, not on a simple count of nodes. Excluding one element removes only that element's contribution, and if the same rule still fails on other elements, or higher-severity issues remain elsewhere, the score stays roughly the same. Excluding elements is meant to remove genuinely irrelevant UI, not to raise a score.\n\n**Fixes.**\n\n*   **Confirm the element was actually removed** using the section above, then look at whether the same rule still fails elsewhere.\n*   **Address the underlying violations** rather than filtering, when the elements are part of your application. See [Improve accessibility](/llm/markdown/accessibility/guides/improve-accessibility.md) and [How the accessibility score is calculated](/llm/markdown/accessibility/core-concepts/accessibility-score.md).\n",
      "section": "accessibility",
      "anchors": [
        "your-score-didnt-improve-after-excluding-an-element"
      ],
      "path": "/llm/json/chunked/accessibility/troubleshooting.json",
      "token_estimate": 187
    },
    {
      "id": "accessibility/troubleshooting#a-rule-keeps-failing-and-you-cant-resolve-it-yet",
      "doc_id": "accessibility/troubleshooting",
      "heading": "A rule keeps failing and you can't resolve it yet",
      "heading_level": 2,
      "content_markdown": "## A rule keeps failing and you can't resolve it yet\n\nA known issue, a false positive, or a third-party defect is failing a rule, and you need to stop it from blocking work without hiding it everywhere.\n\n**Cause.** Cypress Accessibility keeps results broad on purpose so you retain full visibility of every issue in Cypress Cloud. Deciding what should _block_ is a separate, opt-in step, so the right tool depends on whether you want to suppress a single element, change how a rule runs, or enforce a policy in CI.\n\n**Fixes.**\n\n*   **Ignore a rule on one specific element** with the [`data-a11y-ignore` attribute](/llm/markdown/accessibility/configuration/ignoring-rules-per-element.md) in your application markup, which is the most surgical option and keeps the rule active everywhere else.\n*   **Turn a rule off or adjust how Axe Core® runs** across the report with [Axe Core® configuration](/llm/markdown/accessibility/configuration/axe-core-configuration.md), when a rule doesn't apply to your application at all.\n*   **Keep the rule visible but non-blocking** by handling it in your CI policy instead of in Cypress Cloud. The [Results API](/llm/markdown/accessibility/results-api.md) gives you full control over which rules fail a build, so you can allow a known violation while still failing on anything new. See [Block pull requests and set policies](/llm/markdown/accessibility/guides/block-pull-requests.md).\n",
      "section": "accessibility",
      "anchors": [
        "a-rule-keeps-failing-and-you-cant-resolve-it-yet"
      ],
      "path": "/llm/json/chunked/accessibility/troubleshooting.json",
      "token_estimate": 268
    },
    {
      "id": "accessibility/troubleshooting#third-party-or-out-of-scope-ui-is-adding-noise",
      "doc_id": "accessibility/troubleshooting",
      "heading": "Third-party or out-of-scope UI is adding noise",
      "heading_level": 2,
      "content_markdown": "## Third-party or out-of-scope UI is adding noise\n\nChat launchers, cookie banners, analytics overlays, or entire pages you don't own are contributing violations that aren't yours to fix.\n\n**Cause.** Cypress Accessibility checks whatever renders in the states your tests reach, including third-party widgets and any URL your tests visit. Each is reported until you exclude it.\n\n**Fixes.**\n\n*   **Remove third-party elements** with [`elementFilters`](/llm/markdown/accessibility/configuration/elementfilters.md), which drops them from the report and the score.\n    \n*   **Exclude whole URLs you don't intend to cover** with [`viewFilters`](/llm/markdown/accessibility/configuration/viewfilters.md). To keep only your own application's URLs, list `include: true` rules for them followed by a catch-all `{ \"pattern\": \"*\", \"include\": false }`; because the first matching rule wins, the catch-all must come last.\n    \n    App Quality Config\n    \n    ```\n    {  \"viewFilters\": [    {      \"pattern\": \"https://status.my-app.com/*\",      \"include\": false,      \"comment\": \"External status page, linked from the footer but out of scope\"    }  ]}\n    ```\n",
      "section": "accessibility",
      "anchors": [
        "third-party-or-out-of-scope-ui-is-adding-noise"
      ],
      "path": "/llm/json/chunked/accessibility/troubleshooting.json",
      "token_estimate": 192
    },
    {
      "id": "accessibility/troubleshooting#violation-selectors-use-unstable-or-unhelpful-identifiers",
      "doc_id": "accessibility/troubleshooting",
      "heading": "Violation selectors use unstable or unhelpful identifiers",
      "heading_level": 2,
      "content_markdown": "## Violation selectors use unstable or unhelpful identifiers\n\nThe selectors shown for a violation point at framework-generated `id`s or hashed classes, or the same real element appears under different selectors across snapshots, making issues hard to find and deduplicate.\n\n**Cause.** Cypress Accessibility builds an element's identity from its attributes and position in the DOM (see [Element identification](/llm/markdown/accessibility/core-concepts/element-identification.md)). When an identifying attribute changes on every render, the same element can be reported inconsistently. Cypress already ignores the most common unstable values, so add configuration only when your application produces unstable identifiers the built-in filters don't cover.\n\n**Fixes.**\n\n*   **Prefer your own stable attribute** in violation selectors with [`significantAttributes`](/llm/markdown/accessibility/configuration/significantattributes.md). Attributes you list are checked before the defaults, so a stable `data-cy` or `data-test` produces clearer, more consistent selectors. Listing `aria-label` also turns the report into an inventory of your label text.\n    \n    App Quality Config\n    \n    ```\n    {  \"significantAttributes\": [\"data-cy\"]}\n    ```\n    \n*   **Ignore the dynamic attribute** with [`attributeFilters`](/llm/markdown/accessibility/configuration/attributefilters.md) so identification falls back to a stable attribute. When you filter a dynamic `id`, also filter the attributes that reference it, such as `for`, `aria-labelledby`, and `aria-describedby`. Patterns match the whole value (they're anchored as `^(...)$`), and JSON requires backslashes to be doubled, so a token like `\\d` must be written `\\\\d`.\n",
      "section": "accessibility",
      "anchors": [
        "violation-selectors-use-unstable-or-unhelpful-identifiers"
      ],
      "path": "/llm/json/chunked/accessibility/troubleshooting.json",
      "token_estimate": 275
    },
    {
      "id": "accessibility/troubleshooting#a-configuration-rule-has-no-effect",
      "doc_id": "accessibility/troubleshooting",
      "heading": "A configuration rule has no effect",
      "heading_level": 2,
      "content_markdown": "## A configuration rule has no effect\n\nYou saved a rule, but the report looks the same.\n\nWork through these causes in order:\n\n*   **The run predates the change.** Reports use the configuration saved when they were processed. [Regenerate](/llm/markdown/accessibility/configuration/overview.md#Setting-Configuration) the run to apply your current configuration. This is by far the most common cause.\n*   **An earlier rule matched first.** For [`elementFilters`](/llm/markdown/accessibility/configuration/elementfilters.md) and [`viewFilters`](/llm/markdown/accessibility/configuration/viewfilters.md), the **first** matching rule wins, so a broad rule above your specific one prevents it from applying. List specific rules first, and place `include: true` exceptions before the `include: false` rule they should override.\n*   **A nested list replaced a root one.** Nesting a shared property such as `elementFilters` or `attributeFilters` under an `accessibility` or `uiCoverage` key **completely replaces** the root-level list for that product; the two are never merged. Repeat any root rules you still want in the nested list.\n*   **The pattern or selector doesn't match.** `attributeFilters` patterns are anchored to the whole value, so `value: \"user\"` matches only the exact string `user`; use `value: \"user-.*\"` for a prefix. Selectors must match the element Axe Core® reports, not a wrapper around it.\n*   **The configuration didn't save.** Cypress Cloud validates against a strict schema and rejects any property it doesn't recognize, including a misspelled name, a value of the wrong type, or a freeform note on a field that doesn't accept one. Keep notes in a [`comment`](/llm/markdown/accessibility/configuration/overview.md#Comments), and correct the flagged property so the configuration can save.\n",
      "section": "accessibility",
      "anchors": [
        "a-configuration-rule-has-no-effect"
      ],
      "path": "/llm/json/chunked/accessibility/troubleshooting.json",
      "token_estimate": 324
    },
    {
      "id": "accessibility/troubleshooting#a-profile-isnt-being-applied",
      "doc_id": "accessibility/troubleshooting",
      "heading": "A profile isn't being applied",
      "heading_level": 2,
      "content_markdown": "## A profile isn't being applied\n\nYou tagged a run to pick up a [profile](/llm/markdown/accessibility/configuration/profiles.md), but the run used your base configuration instead.\n\n**Cause.** Profiles are selected by matching a run's tags, and a profile applies only when the run carries a tag its rules match. A profile also **overrides** the base configuration for the matched run rather than merging with it, so a partial profile can look like \"nothing changed\" if you expected your base rules to still apply.\n\n**Fixes.**\n\n*   **Confirm the run was tagged** with a value the profile matches, for example `cypress run --record --tag \"aq-config-pr\"`.\n*   **Include every rule the run needs in the profile**, since the profile replaces the base configuration for matched runs rather than merging.\n*   **Check tag precedence** when a run carries multiple matching tags. See [Profiles](/llm/markdown/accessibility/configuration/profiles.md) and the profile questions in the [FAQ](/llm/markdown/accessibility/faq.md).\n",
      "section": "accessibility",
      "anchors": [
        "a-profile-isnt-being-applied"
      ],
      "path": "/llm/json/chunked/accessibility/troubleshooting.json",
      "token_estimate": 191
    },
    {
      "id": "accessibility/troubleshooting#still-stuck",
      "doc_id": "accessibility/troubleshooting",
      "heading": "Still stuck?",
      "heading_level": 2,
      "content_markdown": "## Still stuck?\n\n*   The [Cypress Accessibility FAQ](/llm/markdown/accessibility/faq.md) answers focused questions about ignoring elements and URLs, element identification, configuration, and profiles.\n*   The [Configuration overview](/llm/markdown/accessibility/configuration/overview.md) covers where configuration lives, how it's scoped, and how to regenerate reports.\n*   [How Cypress Accessibility works](/llm/markdown/accessibility/core-concepts/how-it-works.md) and [How the accessibility score is calculated](/llm/markdown/accessibility/core-concepts/accessibility-score.md) explain what the report measures.\n*   If a report still looks wrong after working through this page, reach out to your Cypress point of contact with a link to the run.\n",
      "section": "accessibility",
      "anchors": [
        "still-stuck"
      ],
      "path": "/llm/json/chunked/accessibility/troubleshooting.json",
      "token_estimate": 107
    }
  ]
}