VitalSentinel Documentation

This guide covers common issues and their solutions. If you can't find your answer here, contact support.

Script Issues

RUM Script Not Loading

See RUM Script Installation for setup instructions.

Symptoms:

No RUM data appearing in dashboard
Script not visible in Network tab

Solutions:

Check installation
- Verify script is in <head> section
- Ensure data-key is correct
- Confirm async attribute is present
Check for blockers
- Disable ad blockers temporarily
- Check Content Security Policy headers
- Test in incognito mode
Verify domain
- Tracking ID must match your domain
- Check for typos in the domain URL
Test locally
- Add data-debug="true" to script
- Check console for [VitalSentinel RUM] messages

Web Analytics Script Not Tracking

See Web Analytics Script Installation for setup instructions.

Symptoms:

No pageviews in Web Analytics
Events not appearing

Solutions:

Same checks as RUM (above)
Check consent settings
- Default storage is "none" (no persistence)
- May need to call grantConsent() for returning visitor tracking
SPA navigation
- Verify SPA detection is working
- Try data-spa="true" explicitly
- Or call trackPageView() manually

E-commerce Not Auto-Detecting

See Web Analytics for supported platforms and setup.

Symptoms:

Platform not detected
E-commerce events not tracked

Solutions:

Verify platform
- Check window.VitalSentinelAnalytics.getDebug().ecommercePlatform
- Ensure you're on a supported platform
Platform-specific
- Shopify: Check window.Shopify exists
- WooCommerce: Check for WooCommerce body classes
- Ensure checkout pages are accessible
Timing issues
- Script may load before platform objects
- Try adding script after platform scripts

Script Loads but No Events Fire

Symptoms:

Script tag is in the page and the file downloads (200 status)
Network panel shows no beacon requests to *.vitalsentinel.com

Solutions:

Check Content Security Policy
- Add connect-src https://rum.vitalsentinel.com https://analytics.vitalsentinel.com (and script-src for the script files)
- Errors show in browser console as "Refused to connect" / "Refused to load"
Enable debug mode
- Add data-debug="true" to the script tag
- Console logs every event the script tries to send and any error
Verify the tracking ID
- A typo in data-key causes the backend to silently drop events
- Re-copy the ID from the domain edit page

Symptoms:

One route change produces two or three pageview events
Bounce rate looks abnormally low

Solutions:

Disable manual + automatic tracking
- If your code calls trackPageView() after route changes and data-spa is set to auto, both fire
- Pick one: either set data-spa="false" and call trackPageView() manually, or leave auto-detection on and remove the manual calls
Check the framework router
- Some routers fire popstate and pushState for the same navigation
- Use the framework's "route change complete" hook for manual tracking

Script Blocked by Ad Blockers

Symptoms:

Some visitors see no events; others see them fine
Console shows "blocked by client" or generic network errors only on certain machines

Solutions:

Privacy-focused ad blockers (uBlock Origin, Brave Shields) sometimes match *analytics* and *rum* paths.
Self-hosting the script on your own subdomain can avoid this. Contact support for the self-hosting setup.
Educate users to allowlist your site if ad-blocking is suppressing first-party analytics.

CORS / Preflight Errors in Browser Console

Symptoms:

Access-Control-Allow-Origin errors when the script tries to send beacons
Events are dropped entirely

Solutions:

The collector endpoints support CORS for any origin – CORS errors usually mean a corporate proxy or local interceptor is rewriting headers.
Test from a clean network and a clean browser profile.
If the error references a different host (your CDN, your gateway), the issue is upstream of VitalSentinel.

`data-key` Mismatch Between Staging and Production

Symptoms:

Staging traffic shows up in production analytics, or vice versa
Numbers spike unexpectedly after a deploy

Solutions:

Each domain in VitalSentinel has its own tracking ID. Add a separate domain for staging and use the staging ID in non-prod environments.
A common pattern: build-time environment variable (NEXT_PUBLIC_VS_KEY) that resolves to the right ID per environment.

No Data Appearing

RUM Data Missing

Symptoms:

Dashboard shows no RUM metrics
Core Web Vitals empty

Timeline:

Initial data: 15-30 minutes after installation
Full metrics: May take 24 hours for complete picture

Solutions:

Wait for data
- Visit your site to generate traffic
- Wait 15-30 minutes
- Refresh the dashboard
Check sample rate
- Default is 1.0 (100%)
- If set lower, you need more traffic
Verify script execution
- Check browser console for errors
- Enable debug mode
- Confirm network requests are sent

Uptime Data Missing

See Uptime Monitoring for configuration details.

Symptoms:

No uptime status shown
"No data" message

Solutions:

Domain accessibility
- Verify domain is publicly accessible
- Check for firewall blocking
- Confirm DNS is resolving
Check interval
- Wait for at least one check cycle
- 5-minute interval = wait 5 minutes
SSL issues
- Invalid SSL may cause check failures
- Verify certificate is valid

CrUX Data Missing

See CrUX Monitoring for more about how CrUX works.

Symptoms:

CrUX shows "No data available"

Solutions:

Traffic requirements
- CrUX requires significant Chrome traffic
- Low-traffic sites may not have data
Data availability
- CrUX updates monthly
- New sites may take 28+ days
URL specificity
- Try origin-level data instead of URL-level
- Popular pages have better coverage

Synthetic Tests Stuck on "Pending" or "Failed"

Symptoms:

A scheduled URL never produces a result
Detail view shows "Failed" with no data

Solutions:

Verify the URL is reachable from public networks – Synthetic runs from VitalSentinel's monitoring IPs and a WAF block prevents tests from completing.
Lighthouse fails fast on pages that take longer than ~60s to fully load. Check the URL manually in PageSpeed Insights – if PSI fails too, the page is too slow for any Lighthouse runner.
For Custom Pod locations, an outage in a single region can produce one failed run while other locations succeed. Check the per-location tab.

GSC Connected but Performance Tab Shows Zero Clicks

Symptoms:

Workspace Integrations shows the Google account as Connected
The GSC overview shows zero clicks/impressions even though the GSC UI shows traffic

Solutions:

Verify the linked property
- Open the domain edit page and confirm the right GSC property is selected
- For Domain properties, the property should match the apex domain; for URL-prefix, it should match the exact host
Wait for the initial sync
- Initial GSC backfill can take up to 24 hours after linking
- The dashboard banner indicates whether the first sync has completed
Check date range
- GSC data is delayed 2–3 days. A 24-hour date range may show zeros while a 7-day range shows data.

GA4 Connected but "No Property Selected" Persists

Symptoms:

Google account shows Connected on Integrations
Domain edit page GA4 dropdown is empty or doesn't save

Solutions:

The connected Google account must have at least Viewer access to the GA4 property. Verify in Google Analytics → Admin → Property Access Management.
If the property is owned by a different Google identity, connect that account instead via Workspace Integrations.
After fixing access, click Refresh on the Integrations row to repull the property list.

Indexing Data Shows "Inspection Unavailable" for Many URLs

Symptoms:

Many sitemap URLs show "Inspection unavailable" or no status
Indexing dashboard looks sparse

Solutions:

Google's URL Inspection API is rate-limited per GSC property and shared with anything else that calls it. Coverage of large sitemaps typically fills in over several days as inspections cycle through.
A focused sitemap (priority URLs only) gets full coverage faster than a kitchen-sink sitemap.
If you suspect a stuck integration, reconnect the Google account from Workspace Integrations and let the next sync run.

Inspector Run Aborted with "URL Validation Failed"

Symptoms:

Submitting a URL produces an immediate "URL validation failed" without consuming quota

Solutions:

The URL must be http:// or https:// and resolve to a public IP. Localhost, private IPs (10.x, 192.168.x), and link-local addresses are rejected.
A quota unit is not charged for validation failures, only for runs that start.
For private/staging URLs, expose them publicly behind auth or use Synthetic Monitoring with a VitalSentinel allowlist.

Robots.txt Monitor Reports a Change but the File Looks Identical

Symptoms:

Alert fires, you fetch the file, and the contents look unchanged

Solutions:

The diff is computed on the raw bytes returned to our crawler. Whitespace, BOMs, line-ending changes (CRLF vs LF), or a temporary 5xx returning HTML count as changes.
View the diff in the Robots.txt monitor detail page – the highlighted region tells you exactly what changed.
If the change was a transient server error, it'll self-resolve on the next successful fetch.

Sitemap Scan Returns 0 URLs

Symptoms:

"Scan complete – 0 URLs" after a sitemap rescan

Solutions:

Verify robots.txt references a sitemap (Sitemap: https://example.com/sitemap.xml) or that the sitemap is at /sitemap.xml or /sitemap_index.xml.
Sitemap indexes pointing to gzipped sub-sitemaps are supported; pointing to non-XML formats is not.
If the sitemap requires basic auth or is behind a WAF that blocks our monitoring IPs, the fetch fails silently. Allowlist our IPs.

Uptime Shows "Down" but the Site Loads Fine in My Browser

Symptoms:

Repeated downtime notifications while the site appears healthy

Solutions:

Cloudflare, AWS WAF, or geo-blocking can serve a 403/503 to specific IP ranges while a normal request succeeds. Allowlist our monitoring IPs.
The check runs from one or more fixed regions – an outage in your CDN's nearest POP to those regions can cause real downtime that's invisible from your location.
Inspect the Uptime detail page for the exact status code and response time of each failed check.

Performance Issues

Slow Dashboard Loading

Symptoms:

Dashboard takes long to load
Metrics loading slowly

Solutions:

Reduce time range
- Shorter periods load faster
- Try "Last 7 days" instead of "Last 90 days"
Browser issues
- Clear browser cache
- Try incognito mode
- Test different browser

High Latency in Reports

Solutions:

Reduce complexity
- Fewer metrics per view
- Smaller date ranges
Check connection
- Slow internet affects loading
- Try from different network

Dashboard Cards Stuck on the Loading Skeleton

Symptoms:

One or more cards on the main dashboard never finish loading
Other cards on the same page render normally

Solutions:

Hidden modules in the Customize modal don't fetch – stuck cards are usually a backend timeout for one slow query.
Reduce the dashboard time range (e.g., 28 days → 7 days) and reload. Long ranges over many domains hit per-query timeouts first.
If the issue persists, identify which module is stuck (its skeleton has the module name) and report it to support with the workspace and domain ID.

GSC Deep-Dive Report Doesn't Finish

Symptoms:

One of the GSC deep-dive reports (Opportunities, Cannibalization, Clusters, etc.) keeps loading

Solutions:

These reports run on demand against your GSC dataset and can take a while on large properties. Give it some time before assuming it's stuck.
If it never finishes, the underlying GSC token may have lapsed – check Workspace Integrations for a Reconnect badge and reconnect if needed.
Refreshing the page re-runs the report.

Alert Issues

See Setting Up Alerts and Notifications for configuration details.

Not Receiving Alerts

Symptoms:

Alerts trigger but no notification
Email not received

Solutions:

Check email settings
- Verify email is enabled in Email Preferences (Settings → Emails)
- Check spam/junk folder
- Confirm email address is correct
Check alert configuration
- Verify alert is enabled
- Check if "Send email" is enabled for the specific alert
- Ensure threshold conditions are correct
Check conditions
- Verify condition is actually met
- For Synthetic alerts, check evaluation window settings
- View alert history in dashboard

Too Many Alerts

Symptoms:

Alert fatigue
Constant notifications

Solutions:

Adjust thresholds
- Set more reasonable values
- Account for normal variance
For Synthetic alerts, increase evaluation window
- Average over more tests (last 5 or 10) reduces noise
- Only alert on sustained issues
Review alert set
- Remove redundant alerts
- Disable alerts you don't need

Alert Keeps Firing and Resolving in a Tight Loop (Flapping)

Symptoms:

The same alert toggles between Triggered and Resolved several times per hour
Inbox fills up with paired notifications

Solutions:

Increase the evaluation window so a single noisy datapoint can't toggle state. For Synthetic, average over the last 5–10 runs.
Add hysteresis: the resolve threshold should be a few percent better than the trigger threshold so a metric oscillating around the line doesn't flap.
For Uptime, increase the consecutive-failure count required to declare an incident.

Email Alerts Went to Spam

Symptoms:

Email is enabled and the alert is triggering, but nothing arrives in the inbox

Solutions:

Check spam/junk and the "Updates" / "Promotions" tabs.
Add noreply@vitalsentinel.com and alerts@vitalsentinel.com to your address book or allowlist.
Corporate mail servers sometimes silently quarantine bulk-pattern emails – ask IT to allowlist vitalsentinel.com if multiple team members report missing emails.

Synthetic Alert Fired on a One-off Run

Symptoms:

Single bad Lighthouse run triggered an alert; next run was healthy again

Solutions:

Synthetic naturally varies 3–5 points run-to-run. Set the evaluation window to "average of last 5 runs" or higher so an alert needs sustained badness.
For Core Web Vitals alerts, prefer a P75-over-N-runs threshold over a single-run threshold.

Integration Issues

See Google Analytics and Google Search Console for integration setup.

Google Account Won't Connect

Symptoms:

OAuth fails
"Access denied" error

Solutions:

Permissions
- Ensure you have access to the property
- Check you're using the right account
Re-authorize
- Disconnect and reconnect
- Grant all requested permissions
Third-party cookies
- Enable cookies for OAuth flow
- Try different browser

Google Data Not Syncing

Symptoms:

GA4 or GSC data not appearing
Stale data

Solutions:

Check connection
- Verify integration is connected
- Re-authorize if expired
Property linking
- Ensure correct property is linked
- GA4 (not UA) for Analytics
Data delays
- GA4: Up to 24 hours
- GSC: 2-3 days delay

"Reconnect" Badge Keeps Coming Back After Re-authorizing

Symptoms:

The Workspace Integrations row shows Reconnect, you click and re-authorize, the badge returns later

Solutions:

Try a full disconnect-reconnect cycle: delete the account from the Integrations list, revoke VitalSentinel from your Google Account permissions, then re-add the account from Integrations.
If the issue persists, the Google account may have a security policy (Workspace admin policy, MFA requirement) that revokes long-lived tokens. Try a personal Google account to confirm whether the policy is the cause.
If you're still stuck after both steps, contact support@vitalsentinel.com with the affected account email.

GA4 Data Shows a Different Number Than the GA4 UI

Symptoms:

Total users / sessions / events differ between VitalSentinel and the GA4 reports UI

Solutions:

GA4 applies sampling above certain row thresholds; the API returns sampled estimates. The GA4 UI sometimes uses an unsampled fallback.
For exact figures, refer to GA4 Explorations directly. VitalSentinel matches the GA4 reporting API output, which is what most automated tooling sees.
Date ranges anchored to different timezones (account vs. domain timezone) also produce small deltas.

GSC Properties Don't Include My Domain

Symptoms:

Workspace Integrations is connected; domain edit page GSC dropdown is empty

Solutions:

The connected Google account must be an Owner or Full user on the GSC property. Verify in Search Console → Settings → Users and permissions.
Domain properties (DNS-verified) and URL-prefix properties (URL-verified) both work, but the property must be verified.
After granting access, click Refresh on the Integrations row to repull the property list.

Billing & Plan Issues

Stripe Checkout Fails with "Card Declined"

Symptoms:

Checkout returns "Your card was declined" or similar

Solutions:

Check with your card issuer – many banks block first-time international charges by default.
Try a different card or use a card with international transactions enabled.
For corporate cards, the merchant category code may be on a deny-list; switch to a personal card to confirm and ask your finance team to allowlist Stripe.

I Downgraded but My Plan Still Shows the Old Tier

Symptoms:

After scheduling a downgrade, the workspace still appears on the higher plan

Solutions:

Downgrades take effect at the end of the current billing period, not immediately. The Billing page shows a banner with the scheduled change and the effective date.
To cancel a scheduled downgrade, click Keep Current Plan in the banner.
To downgrade immediately, you'd need to cancel and resubscribe – contact support for prorated handling.

Cancel Subscription Button Is Disabled

Symptoms:

Cancel Subscription is greyed out on the Billing page

Solutions:

The most common cause is a payment in a failed state. Resolve it via the Stripe billing portal first, then try cancel again.
If the subscription is already scheduled to cancel at period end, the button is replaced with "Resume Subscription".
For other cases, contact support@vitalsentinel.com.

Symptoms:

You updated your card in the Stripe portal but the workspace still shows "Payment Required"

Solutions:

Stripe retries the failed invoice on a schedule; the banner clears automatically when the retry succeeds.
Click Update Payment in the banner to manually retry the failed invoice immediately.
If the new card is also declined, repeat the steps in Stripe Checkout Fails.

I'm Being Charged in the Wrong Currency

Symptoms:

Invoice currency doesn't match the workspace billing country

Solutions:

Currency is locked when the workspace was first subscribed. Open the Stripe portal and update the billing country first; the next renewal can be issued in the new currency.
For an immediate currency switch, cancel and resubscribe – contact support to coordinate so coverage isn't interrupted.

Workspace & Domain Issues

Can't Delete a Domain

Symptoms:

Delete Domain button is disabled or returns "Domain in use"

Solutions:

The domain may be referenced by an active Report template or alert. Remove those references first, then retry.
The domain may be the linked target of a custom integration. Disable the integration on the domain edit page first.
If neither applies, contact support – domains in unusual states sometimes need manual cleanup.

Can't Delete Account

Symptoms:

Delete Account button shows "Cancel subscription first"

Solutions:

You own a workspace with an active paid subscription. Either:
- Cancel the subscription on the workspace's Billing page and let the current period end, or
- Transfer ownership to another team member from the Members page.
After the workspace is unowned/free, retry account deletion. See Account Settings.

"Domain Not Accessible" Error When Adding a New Domain

Symptoms:

Add Domain returns "We couldn't reach this URL"

Solutions:

VitalSentinel performs a one-time check from public IPs before adding the domain. Cloudflare, AWS WAF, or country-blocking can deny that initial probe.
Allowlist our monitoring IPs and retry.
If the domain is private/staging, expose a public route or a sitemap that's reachable from the public internet.

Invited Team Member Never Received the Email

Symptoms:

The Members page shows the invitation as Pending, but the recipient says they got nothing

Solutions:

Ask the recipient to check spam/junk and any "Updates" / "Promotions" tabs.
Re-send by deleting the pending invitation and re-inviting (the new email goes out fresh).
For corporate inboxes, ask IT to allowlist noreply@vitalsentinel.com.

Removed a Member but They Still Show "Pending"

Symptoms:

You deleted an invitation, but the row shows up again

Solutions:

"Pending" is the invitation state, not the user state. Deleting the invitation removes the pending row; if you don't see the change, refresh the Members page.
If the member already accepted the invitation before you removed it, they're a full member – use the row action to remove their access (not just delete the invitation).

Inspector Issues

Inspector Quota Exhausted Before Month-End

Symptoms:

Run inspection button is disabled with "Quota exhausted"

Solutions:

The quota chip in the top-right shows the reset date. The cycle anchors to your workspace's activation day, not the calendar 1st.
To run more tests this cycle, upgrade the workspace plan – the new quota takes effect immediately.
A test counts as one quota unit even if individual checks failed; URL-validation rejects do not count. See Inspector Quota.

CrUX Check Returns "no_data" Inside Inspector

Symptoms:

Inspector completes but the CrUX section says "no_data"

Solutions:

This is not an error – it means Google doesn't have enough Chrome traffic for the URL or origin to publish CrUX data.
Try the origin URL (e.g., https://example.com/) instead of a deep page – origin-level data has broader coverage.
Low-traffic sites may never have CrUX data. Use RUM for the same metrics from your real visitors.

WHOIS Check Fails for My TLD

Symptoms:

Inspector reports "WHOIS check failed" or shows nothing for the registrar

Solutions:

Several country-code TLDs (e.g., .eu, .de, .uk, .jp) don't expose public WHOIS due to privacy regulations. The check fails by design – see the supported list in Uptime Monitoring.
This doesn't affect your Inspector Score's other pillars.

Inspector Score Lower Than Expected for a Fast Page

Symptoms:

The page is genuinely fast, but Inspector Score is in the 60s or 70s

Solutions:

Inspector Score combines five pillars: Performance, SEO, Security, Infrastructure, Availability. A fast Lighthouse run can still drop the score if SSL is expiring soon, the SEO snapshot is missing meta tags, or robots.txt blocks the URL.
Open the Issues panel – it lists the exact findings with severity and category, so you can see which pillar dragged the score down. See Inspector Score for the formula.

Account Issues

Can't Log In

Solutions:

Password reset
- Use "Forgot password" link
- Check email for reset link
2FA issues
- Use backup codes
- Contact support for recovery
Email verification
- Check for verification email
- Resend verification

Locked Out of Account

Solutions:

Wait and retry
- Too many attempts triggers lockout
- Wait 15-30 minutes
Password reset
- Reset password to unlock
Contact support
- If persistent issues

Lost 2FA Device with No Backup Codes

Symptoms:

Authenticator app is gone, backup codes can't be found

Solutions:

Contact support@vitalsentinel.com from your account email. Recovery requires identity verification and is handled manually – plan on at least one business day.
After recovery, immediately re-enable 2FA and store the new backup codes in a password manager.