Troubleshooting

A whole area is missing from the report

An area only appears when at least one of its checks produced a finding. If every check in it was disabled or skipped, there is nothing to score and the area is left out rather than shown as a zero.

The most common cause is the database area on a PostgreSQL site — those checks are MySQL and MariaDB specific and skip themselves deliberately.

Lots of checks are skipping

Open the scan and read the reason each one gives; they are specific. The usual causes:

  • Shell probes are off, or the host blocks them. The server area needs to run short read-only commands (nproc, free) to report CPU and memory. Check Allow shell probes in settings; if it is on and they still skip, the host has disabled shell_exec and there is nothing to be done about it.
  • The database user lacks a privilege. Some server status variables need more than the schema-level grants a Craft database user normally gets.
  • The scan came from the CLI. There is no HTTP request to inspect, so compression and protocol checks have nothing to look at. Run the scan from the control panel instead.

Skipping is not failing. A skipped check is excluded from the score entirely, so a host that hides things does not drag the number down.

The CLI and the control panel disagree about PHP

They are reading different PHP configurations, and this is expected. The CLI SAPI usually has a much larger memory_limit, no max_execution_time, and very often no OPcache — a CLI scan reporting “OPcache is disabled” may be describing a perfectly well-configured web server.

Every scan records its SAPI in the report header. For the PHP area, trust the scan whose SAPI is fpm-fcgi (or apache2handler) — that is, one started from the control panel. The other five areas give the same answer either way.

“OPcache is disabled” but I know it is on

Almost always the SAPI question above. If a control panel scan also reports it off, check that opcache.enable is set in the PHP-FPM pool’s ini and not only in the CLI one, and remember that ini_get() returns the string "Off" for some disabled directives — a value that naive code reads as true. Microscope parses these against an explicit truthy list, so if it says off, it means off for the runtime it measured.

The PDF button does nothing, or redirects to the print view

dompdf is not installed. It is an optional dependency — install it with composer require dompdf/dompdf, or use the print view and let the browser save the PDF, which produces better typography anyway.

If your Composer audit policy refuses to install dompdf, that is the exact situation the optional dependency exists for: every published dompdf release carries an advisory. Use the print view.

Scheduled scans never run

Work through this in order:

  1. Is Run scans on a schedule actually on in settings?
  2. Run php craft microscope/scan/scheduled by hand. It reports whether a scan was due. If it says one was and starts it, your schedule is fine and the trigger is the problem.
  3. If the trigger is cron: confirm the cron job runs at all, that it cds into the project root first, and that it uses the same PHP binary you use interactively.
  4. If the trigger is control panel requests: the check only happens while somebody is using the control panel. On a site nobody logs into, the scan waits until somebody does. That is the documented trade-off; switch to cron if it matters.
  5. Check craft.microscope.nextScheduledScan() or the settings screen for when Microscope thinks the next one is due — the hour is in the system timezone, which may not be yours.

A scan starts and never finishes

Control panel scans run through Craft’s queue. If the scan sits at pending, the queue is not running — which, usefully, is itself one of the things Microscope checks. Run php craft queue/run to confirm, then fix the queue runner properly.

A scan that starts and then fails leaves an error in storage/logs/microscope.log. Turn the log level up to info or debug for more detail.

No notification email arrived

  • The default is to send only when something new appears. A scan that found nothing new sends nothing — that is working correctly. Switch When to send to always to test.
  • Test the mail path directly with php craft microscope/scan/run --notify.
  • If a recipient is an environment variable, confirm it resolves in the environment the scan runs in — cron often has a different environment from your shell.
  • Craft’s own email settings have to work. Send a test from Settings → Email first.

Template analysis found nothing, or far too much

  • Nothing: check that Scan templates is on, and that the templates are where Craft thinks they are. Front-end templates under a non-standard root need adding as an extra template directory.
  • Truncated: the default ceiling is 1,500 templates per scan. A site with a large vendored template library will hit it; raise the limit or add only the directories you care about.
  • Too much: the missing-cache-tag rule is advisory by design and fires on shape alone. A template full of queries rendering per-user content should not be cached, and the rule can’t know that — read those findings as prompts, not defects.

A finding I fixed keeps coming back as new

“New since last scan” compares fingerprints against the previous stored scan. If your retention is set very low, or scans are being pruned between runs, there may be no predecessor to compare against and everything looks new. The default of 50 is plenty; anything above a handful works.

Dev mode is reported as a problem on my local site

It should not be. Checks that only make sense in production are aware of the environment, and dev and staging are treated as not-production — devMode is supposed to be on locally, and telling a developer off for it on every scan would train them to ignore the report. If you are seeing it locally, check what CRAFT_ENVIRONMENT is actually set to in that environment.

Still stuck

Open an issue on GitHub with the scan’s SAPI, your Craft and PHP versions, and the relevant lines from storage/logs/microscope.log.