Troubleshoot a custom check that fails unexpectedly

Diagnose target, scope, value, rendering, access, and resource-state mismatches.

Last checked 21 August 2026

Start with the saved rule in the website's Custom Checks card, then compare it with the exact page or site-resource response TechDash evaluated. A value visible in your everyday browser is not proof that the monitoring request received the same content.

Check the rule itself

Review these fields in order:

  1. Look in: Confirm that the value belongs in Head, Body, Content, Headers, Title, H1, robots.txt, or sitemap.xml.
  2. Scope: For a page target, confirm Sitewide or This page is correct. A sitewide rule runs only on monitored URLs.
  3. Page: For This page, verify the selected monitored path.
  4. Match: Is found fails when the value is absent. Isn’t found fails when the value is present.
  5. Value: Check spelling and internal whitespace. Matching ignores letter case, but it is otherwise a literal substring search.

Custom checks do not support regex, wildcards, selectors, XPath, scripts, whole-word matching, or OR expressions. A value such as price.*sale is searched as those literal characters.

Check the selected signal

Head and Body search rendered HTML markup. Content searches the rendered body-text signal. A visitor-facing phrase split by markup may appear naturally on screen but not as one continuous substring in HTML. Conversely, Body can match hidden elements, attributes, and script text that are not visible.

Headers searches formatted response-header lines. Title and H1 search their extracted page signals. Put the header name in the value when a short token could occur elsewhere.

For page rules, normal availability gates run first. A non-successful response can cause optional checks to be skipped, and non-HTML responses do not provide the usual HTML signals. Resolve the HTTP, redirect, challenge, or document-type problem before diagnosing a missing title or H1 value.

Check the response TechDash received

Differences can come from:

  • HTTP Basic Authentication credentials.
  • The selected User agent.
  • WAF, CDN, or bot protection behavior.
  • Consent banners and personalization.
  • Geography, cookies, or session state.
  • Client-side rendering and late-loading content.
  • A redirect to a different path or hostname.
  • A deployment that changed generated markup.

Run the monitored page again and review the resulting incident and current URL. If the site requires HTTP Basic Authentication, verify Username, Password, HTTPS certificate, and server access policy under Advanced Settings. A form-based sign-in is not supported by those fields.

Check robots.txt and sitemap.xml state

Resource custom checks run with Site Resources, not an ordinary page check. Review the resource fetch status as well as the custom result.

A failed current fetch can leave the custom rule evaluating previously stored text. This means a passing value assertion does not prove that the latest fetch succeeded. Use the built-in robots or sitemap incident to diagnose reachability.

The sitemap.xml target searches one fetched sitemap file: the first sitemap declared in robots.txt, or /sitemap.xml when none is declared. It does not concatenate every child sitemap in the discovered tree, and the stored searchable text is limited to 100,000 characters. A value found only in a child file or beyond that limit may not match.

Read severity, evidence, and repercussions

A passing Is found rule means the value occurred in the selected signal. A passing Isn’t found rule means it did not. A failure reverses those conditions and opens Custom check failed at the Advisory, Warning, or Critical level saved on the rule.

The incident identifies the assertion and affected page or resource. It does not identify the responsible deployment, prove that matched text is visible, validate a header or XML policy, or show that a matched script executed. The configured severity affects incident ordering, Health Score weighting, and visual treatment. If Send a notification and the relevant channels are enabled, the failure transition can also notify.

A failure can be benign when the requirement intentionally changed, the rule targets the wrong signal, a short substring matches unrelated text, or consent, location, authentication, personalization, or rendering changes the response. Confirm the business requirement and current evidence before lowering severity, ignoring the incident, or editing the value.

Re-test safely

After editing:

  1. Save the rule.
  2. Run the selected monitored page, or use Check now for Site Resources.
  3. Wait for the new run to complete.
  4. Confirm the required value is found or the forbidden value is absent in the fresh evidence.
  5. Verify the result is Good and the incident recovered before changing severity or enabling notifications.

If the rule is noisy while you investigate, change Notify to Incident only rather than deleting useful evidence. Use a more specific literal value when a short substring matches unrelated content. Editing or deleting a rule stops or changes future evaluation, but it is not recovery evidence.

Related articles