Using Diagnostics

This guide is for the people who keep the site running: operators who check whether everything is healthy before and after a release, and the developers they work with. Diagnostics gives you health panels you can read at a glance, plus a few screens that let you run maintenance tasks safely. The health panels are read-only, so looking at them changes nothing. Two screens, the Command Palette and Queue Operations, do take action, so this guide tells you exactly when that happens. Green means healthy. A warning or failure means something needs attention. Every step uses the labels you see on screen.

Using Diagnostics (how-to)

How to read the health widgets on your admin dashboard

1. Open your admin dashboard. The health widgets are grouped together near the top.
2. Read each panel and check its colour. Green means that area is healthy. A warning or failure colour means it needs attention.
3. The panels you will see are Setup health, Cache health, Migrations health, Registry health, Config drift, Content health, Content graph, Tailwind build status, Packages installed, and Public output safety.
4. Setup health lists any Items to complete:. When there is nothing outstanding it shows “All setup requirements met!”.
5. If a panel is green, there is nothing to do. If a panel warns or fails and you are not sure what it means, note the panel name and its message and send it to your developer.

How to review System health

1. Go to System health.
2. Read each panel the same way as on the dashboard: green is healthy, a warning or failure needs attention.
3. Use this screen as your first stop before you change package setup, run a deployment, or alter publishing configuration. It gives you the full picture in one place.
4. If something fails, decide whether it is a thing you can fix yourself (described in the panel) or a thing for a developer, then act or escalate.

How to warm the cache from Cache health

1. Find the Cache health panel, either on your dashboard or on System health.
2. Click Warm cache.
3. The button shows Warming… while it works. When it finishes it shows Last warmed: followed by the time it ran.
4. Warming the cache is safe to do at any time. It refreshes cached data so the next visitor gets an up-to-date page.

How to check pending migrations

1. Find the Migrations health panel on your dashboard or on System health.
2. Read the status. When everything is up to date it shows All migrated along with the Last batch: that ran.
3. If it shows Pending migrations, the database has changes waiting to be applied. This usually follows a deployment and is a job for your developer.
4. If it shows Orphaned registrations, a registered migration no longer matches the files on the site. Note this and pass it to your developer.

How to review installed packages on the developer tools dashboard

1. Go to Diagnostics to open the developer tools dashboard.
2. Find the Packages installed panel. It lists each package with columns for Package, Version, Bundle, Commands, Health, Docs, Admin guide, and README.
3. The Health column tells you at a glance whether each package is in good shape.
4. Each package shows whether its configuration is Config published or Not published. “Not published” means the package is using its shipped defaults, which is normal unless you meant to customise it.
5. Use the Docs, Admin guide, and README links to open a package’s documentation when you need more detail.

How to run a maintenance command from the Command Palette

1. Go to Command Palette.
2. In the search box (placeholder “Search commands, packages, cache, migrations…”), type what you are looking for. Results are grouped under Developer tools and Commands.
3. Pick a result. The screen prompts you to Select a command to review parameters, permission scope, and confirmation requirements. so you can see exactly what the command does before running it.
4. Fill in any parameters the command asks for.
5. If the command needs confirmation, you will see “This operational command requires confirmation before it runs.” For commands that make wider changes you will also see “This command may make broad or destructive operational changes.”
6. When a command requires confirmation, tick the checkbox “I understand this command will run on this application.”
7. Click Run to run it, or Cancel to back out without running anything.

How to audit permissions and roles

1. Go to Permission Audit.
2. Read the Permissions, Roles, and Users sections. Together they show which permissions are registered and how well your roles cover them.
3. Run this audit after you install or remove a package, since that can change which permissions exist.
4. If a permission looks uncovered or a role looks wrong, note it and work with your developer to adjust the roles.

How to check Queue Operations

1. Go to Queue Operations.
2. At the top, read the summary stats: Tracked jobs, Succeeded, Pending, and Failed. This is your quick health check for background work.
3. Switch between the tabs History, Failed jobs, and Pending jobs to focus on what you need.
4. Each row shows a job’s details, including Job, Status, Attempts, Duration, Started at, Finished at, Failed At, and Exception. A status can be Pending, Processing, Running, Succeeded, Failed, or Delayed.
5. To narrow the list by date, use the From and Until filters.

To retry a failed job:

1. Open the Failed jobs tab.
2. Click Retry on a single job to run it again, or Retry failed jobs to retry them all at once.

To delete a pending job:

1. Open the Pending jobs tab.
2. Click Delete pending job on the job you want to remove. This stops it from running.

To prune history:

1. Click Prune history.
2. This clears out old tracked-job records so the list stays manageable. It does not affect jobs that are still waiting to run.

Rolling out Diagnostics (for owners)

Diagnostics is mostly a tool for the people who keep the site running. Decide who looks at it and who is allowed to act from it.

Start with the health widgets

• The health widgets on your admin dashboard and on System health are read-only. Anyone responsible for the site can read them safely. Make these the first thing your team checks when something seems wrong, before escalating.

Who does what

Task	Who
Read the health widgets and System health	Operator or owner: safe to view, nothing can break
Warm the cache from Cache health	Operator: safe to run at any time
Read Migrations health and Config drift	Operator reads; applying migrations or fixing drift is a developer
Review Packages installed on Diagnostics	Operator or developer
Run a command from Command Palette	Developer: these run real commands, some make broad changes
Audit Permission Audit	Administrator reads; changing roles is a developer task
Act on Queue Operations (retry, delete, prune)	Operator or developer, depending on the job

Read-only versus action

• The health widgets only show you information. Reading them cannot change anything.
• The Command Palette and Queue Operations screens do take action. Use them deliberately, read the confirmation messages, and let your developer run anything marked as making broad or destructive changes.

Troubleshooting

What you see	What it means	What to do
A health panel is green	That area is healthy	Nothing to do
Setup health lists Items to complete:	Some setup steps are still outstanding	Work through each listed item until it shows “All setup requirements met!”
Cache health warns	Cached data may be out of date	Click Warm cache; if it still warns, note it for your developer
Migrations health shows Pending migrations	Database changes are waiting to be applied, usually after a deployment	Ask your developer to apply the pending migrations
Migrations health shows Orphaned registrations	A registered migration no longer matches the files on the site	Note it and pass it to your developer
Config drift shows missing	A key in the shipped config is absent from the host. Missing = key in shipped config absent from host	Send the drift details to your developer to reconcile the configuration
Config drift shows stale	A key in the host config is no longer shipped. Stale = key in host config no longer shipped	Send the drift details to your developer; when there is none it shows “No config drift detected”
Tailwind build status shows stale or never built	The site styles have not been built, or were built against older input	Ask your developer to rebuild; fresh means it is up to date
A package shows Not published under Config published	That package is using its shipped default configuration	Normal unless you meant to customise it; otherwise ask your developer to publish its config
A queue job shows Failed	A background job did not complete	Open Failed jobs, read the Exception, then click Retry or share it with your developer
Jobs are stuck on Pending or Delayed	Background work is not being processed	Share the Queue Operations view with your developer
A red check you do not understand	A check failed and the message is unclear	Send the panel name and its message to your developer