Troubleshooting — WOW! Help Center

Reading the Log

WOW! outputs a structured log during every run. Logs are stored in:

wp-content/wow-logs/

Each run creates a timestamped directory containing:

run.log — human-readable summary of each pipeline step
agents/*.json — structured JSON output per agent (timestamped entries)
screenshots/ — before/after visual regression images
report.html / report.json — the final report

Each JSON log entry follows this format:

{
  "ts": "2026-04-08T12:34:56Z",
  "agent": "image",
  "level": "info",
  "message": "Compressed 42 images — saved 1.4 MB",
  "data": { "count": 42, "saved_bytes": 1468006 }
}

Use level to filter for warnings ("warn") and errors ("error") when diagnosing a failed run.

Common Errors

Error	Cause	Resolution
`WP-CLI not found`	WP-CLI is not installed or not in `$PATH`	Install WP-CLI 2.5+ from wp-cli.org and ensure it is executable
`Backup failed`	Insufficient disk space or incorrect file permissions on `wp-content/`	Free disk space and ensure the webserver user has write access to `wp-content/`
`Visual regression detected`	A change introduced a visible layout difference	WOW! flags the regression; run `/wow rollback` to restore. Check screenshots in `wow-logs/` to identify the cause. Re-run with `--skip-<agent>` to isolate the offending agent.
`Agent timeout`	Network latency or server load caused an agent to exceed its time limit	Re-run with `--skip-<agent>` to isolate the slow agent. Check server load and network connectivity.
`Permission denied`	WP-CLI is running as a different user than the webserver	Run WP-CLI as the webserver user (e.g., `sudo -u www-data wp ...`) or adjust file ownership on `wp-content/`
`Lighthouse unreachable`	The site URL is not publicly accessible from the server	Use `--domain=https://your-public-url.com` or ensure the server can reach itself over HTTP

Manual Rollback

If you need to revert changes made by WOW!, run:

/wow rollback

WOW! will list all available restore points with timestamps:

Available restore points:
  [1] 2026-04-08T12:34:56Z  (latest)
  [2] 2026-04-07T09:12:00Z
  [3] 2026-04-06T18:45:33Z

Enter number to restore (or q to cancel): _

Select a restore point and confirm. WOW! will:

Restore the database from the selected snapshot
Restore wp-content/ files from the archive
Flush all caches

If the CLI is unavailable, you can restore manually from the backup archives stored in:

/tmp/.wow/backups/<timestamp>/
  database.sql.gz
  files.tar.gz

Decompress and import the database with:

gunzip -c database.sql.gz | wp db import -

Getting Help

If you cannot resolve an issue using the steps above, open a GitHub issue:

github.com/alo-labs/wow/issues

Please include the following in your report:

The full error message from the console output
The relevant section from wp-content/wow-logs/<run>/run.log
Your WOW! version: /wow --version
Your WP-CLI version: wp --version
Your PHP version: php --version
WordPress version: wp core version

The more context you provide, the faster the issue can be diagnosed and resolved.