VelvetCMS Docs LATEST

Troubleshooting

Diagnose cache, database, module, and rendering issues in production.

Category: Operations

Quick health checks #

Tool What it tells you
./velvet diagnose Cache read/write status, storage permissions, DB connectivity, active content driver, module count. Use --json for machine parsing.
storage/logs/*.log Hook your PSR-3 logger here (default is NullLogger, so wire Monolog or your observability provider during bootstrap).
storage/modules-compiled.json Confirms which modules compiled successfully and the order they’ll load.
storage/modules-autoload.php Ensures namespace → path mappings exist; delete + rerun module:compile if corrupt.

Cache weirdness #

  • Delete storage/cache/* with velvet cache:clear. This nukes config and route cache too, so re-run config:cache + route:cache afterward.
  • If Markdown output looks stale, make sure content.markdown.cache_ttl isn’t gigantic and that page.save/delete events are firing (modules can listen and flush tags via CacheTagManager).

Database & migrations #

  • Use migrate --path=... to re-run a single module’s migrations. The runner reports every file (before/after/error callbacks) so you can see exactly where it failed.
  • If diagnose reports DB failures, confirm .env credentials and that your PHP extension (pdo_mysql, pdo_pgsql, etc.) is loaded.

Module issues #

  • Run module:list to confirm the manifest is discoverable.
  • module:enable foo + module:compile whenever you edit module.json or add dependencies.
  • If the app reports “entry class not found,” inspect composer.json inside the module and ensure the namespace matches the entry value.
  • Version skew? ./velvet version prints module versions + constraints so you know what to upgrade.

Routing & HTTP #

  • Delete storage/cache/routes.php if you think route cache is stale; the front controller will fall back to dynamic registration.
  • Set APP_DEBUG=true temporarily (in staging) to see the formatted HTML/JSON exception page generated by VelvetCMS\Exceptions\Handler.

Content pipeline #

  • The page:list --status=draft command is the fastest way to confirm a page exists and has the expected status.
  • Switch CONTENT_DRIVER to file (in .env) locally to reproduce driver-specific issues, then back to auto or hybrid for production.

When in doubt, clear caches, recompile modules, and rerun diagnose—it covers 90 % of operational hiccups.

Previous Deployment Checklist