Skip to content
SteadyPress
Home SiteReview documentation Troubleshooting

Troubleshooting

This guide covers the most common issues users hit on SiteReview. If your problem is not listed, contact support with the diagnostic information described at the bottom of this page.

1. Action Scheduler is not firing

Symptoms: a scan starts but its sections stay queued indefinitely; sections do not transition to running or complete.

Diagnostic check: navigate to Tools > Site Health > Status in the WordPress admin. If WP-Cron is disabled or no recent cron events are firing, that is the cause.

Resolution options, in order of preference:

  1. Set up a server cron entry pinging WP-Cron every 1 to 5 minutes:
    “
    */2 * * * * curl -s https://example.com/wp-cron.php > /dev/null 2>&1
    “
    Many managed hosts have a UI for this — Kinsta, WP Engine, Cloudways, SiteGround all expose cron management.
  2. Enable WordPress's built-in WP-Cron. In wp-config.php, remove the line define('DISABLE_WP_CRON', true); if it exists.
  3. Use the synchronous fallback. SiteReview detects the missing cron and offers a Run scan now (synchronous, homepage-only, degraded) button. This is a limited-scope scan — homepage only, no Performance, no Mobile Friendly, no Accessibility, no AI narrative. Use only as a stopgap until cron is configured.

2. License activation fails

Symptoms: pasting the license key and clicking Activate surfaces an error rather than transitioning to Active.

Common causes and fixes:

  • license_invalid — the key was typed or pasted incorrectly. Copy it from your license email again, watching for leading or trailing whitespace.
  • license_expired — the license is past its expiry date. Renew through the SteadyPress purchase flow.
  • credits_exhausted — the license has no remaining scan credits. Top up by purchasing an additional credit pack from your SteadyPress account.
  • Network egress blocked — the plugin cannot reach api.steadypress.ai. Check firewall and outbound HTTPS rules.
  • HMAC clock skew — your server clock is more than 5 minutes off from UTC. Sync the server clock (NTP) and retry.

3. PageSpeed Insights rate limit hit

Symptoms: the Performance section fails with a rate-limit error; sometimes Mobile Friendly and SEO are affected too.

Causes and fixes:

  • PSI key not configured. The most common case. Without a key, PSI calls go against Google's shared anonymous quota, which is exhausted in seconds. Enter a free PSI key under Settings > API integrations — the onboarding modal walks you through getting one in about three minutes.
  • Per-minute throttle hit. A free PSI key allows up to 240 queries per minute. If you ran several scans in quick succession, the throttle can trigger. Wait 60 seconds and click Retry section.
  • Daily quota exhausted. A free PSI key allows 25,000 queries per day. Each SiteReview scan uses up to 12. Hitting this cap means you have run roughly 2,000 scans today on the same key — unusual outside automated environments. Wait until the daily reset (midnight Pacific) or use a different key.

4. Scan times out on a large site

Symptoms: a Pro scan stays in the running state for the full 15-minute window and ends with one or more sections marked Failed or Partial.

Diagnostic check: the section that times out is almost always Performance on a site with many pages, slow response times, or both.

Fixes:

  • Reduce the page selection. A 6-page scan with slow first-byte times on each page can push Performance close to its 360-second budget.
  • Confirm the site's TTFB is reasonable (under 1 second is healthy). A site with TTFB > 3 seconds will time out repeatedly.
  • Confirm Action Scheduler is firing on schedule.
  • Click Retry section on the failed section. The retry uses any cached PSI data from the original attempt.

5. Accessibility section blocked by iframe restrictions

Symptoms: the Accessibility section enters a degraded state with the message Accessibility scan blocked by site security headers.

Cause: a security plugin or web server is sending X-Frame-Options: DENY or Content-Security-Policy: frame-ancestors 'none' site-wide. axe-core needs a real DOM and runs in a hidden iframe inside the SiteReview admin tab; the framing block prevents access.

Fix: temporarily allow same-origin framing of /wp-admin/-initiated requests in your security plugin. Common configurations:

  • Wordfence: Wordfence > All Options > Web Application Firewall > Disable WordPress's built-in clickjacking protection — or set frame options to SAMEORIGIN rather than DENY.
  • Sucuri Plugin: Sucuri > Hardening > X-Frame-Options — disable or set to SAMEORIGIN.
  • Solid Security: Solid Security > Tweaks > X-Frame-Options — set to SAMEORIGIN.

After adjusting, click Retry section on Accessibility. Restore the previous setting when the scan is complete.

The trust note here is important: SiteReview is auditing the same WordPress install it is running on, so the audited pages and the admin share an origin. The framing block was added by your security plugin to prevent third-party clickjacking, not to prevent same-origin tools from working.

6. Public report URL returns 404

Symptoms: the clean URL /sitereview-reports/{token}/ returns 404, but the direct URL /wp-content/uploads/sitereview/reports/{token}/ works.

Cause: the WordPress rewrite rule is not installed. Some hosts disable .htaccess rewrites; nginx without WordPress rewrite rules will not handle this rewrite; IIS without URL Rewrite Module will not either.

Fixes:

  • Visit Settings > Permalinks and click Save changes without changing anything. This re-flushes WordPress rewrite rules.
  • Confirm .htaccess is writable on Apache or that your nginx configuration includes the standard WordPress rewrite block.
  • If rewrite cannot be enabled on your host, use the direct uploads URL — it serves the same report. The Public URL pattern field in Settings indicates which form your install is using.

7. Report download exceeds the size cap

Symptoms: the Download HTML button produces a file larger than 5 MB, or the download fails entirely.

Cause: scanned pages contain very large images that get embedded as base64 data URIs. The single-file HTML budget is 3 MB target, 5 MB hard cap.

Fixes:

  • Reduce the page selection to fewer pages.
  • Pre-optimize images on the audited pages. SiteReview embeds whatever is on the page.
  • Open the public URL instead of downloading — the public URL is served as static HTML by the web server and is not subject to the same size constraint.

8. PHP version warning on activation

Symptoms: the plugin refuses to activate with a Requires PHP 8.1 or higher notice.

Fix: upgrade your PHP version. PHP 7.4 reached end-of-life in November 2022; PHP 8.0 reached end-of-life in November 2023. Most managed hosts let you change PHP version in the hosting dashboard. Confirm your active theme and other plugins also support PHP 8.1 or higher before switching.

9. White-label colors fail the contrast warning

Symptoms: after setting Primary or Accent in Settings > White-label, an AA fail badge appears next to the color input.

This is informational only. Save is not blocked. The badge surfaces the WCAG 2.1 contrast ratio for that color on white — Primary requires ≥ 4.5:1 for body text, Accent requires ≥ 3:1 for borders and ≥ 4.5:1 for link text.

Options:

  • Adjust the color until the badge shows AA.
  • Ignore the warning and ship the report anyway — the agency has the final say on its own brand colors.

The warning exists because an accessibility-audit product producing inaccessible reports is a contradiction worth flagging. It is not a guard rail.

Diagnostic information to include in support requests

When contacting support, include as much of the following as you have:

  • WordPress version, PHP version, MySQL or MariaDB version
  • SiteReview plugin version
  • License key email (the email associated with the purchase, not the key itself)
  • The site domain (host) and any subdomains if relevant
  • The report token (the 32-character string in /sitereview-reports/{TOKEN}/)
  • The exact error message or unexpected behavior, with screenshots if possible
  • Output from Tools > Site Health > Info relevant to the issue
  • Whether the issue is reproducible — on every scan, intermittently, or only on a specific site

Use the support form at steadypress.ai/contact with subject SiteReview.

Need more help? Contact support.