Common Incidents

This page lists common symptoms and first checks. Keep production-specific timelines, customer data, credentials, and private host details in internal incident notes.

Failed Website Deploy

First checks:

• Open the failed GitHub Actions run and identify the first failing step.
• If the failure happened before upload, check pnpm install, frontend build, or artifact packaging.
• If the failure happened during upload, check SSH key format, known hosts, port, deploy user permissions, and DEPLOY_PATH.
• If the failure happened inside scripts/deploy.sh, check server logs and the deploy step output.

Common causes:

• missing or malformed deploy secret;
• missing shared .env;
• deploy user cannot write to the release directory;
• Composer install failure on the server;
• database migration failure;
• invalid Laravel config cache after an environment change.

If the previous release is still healthy, keep the site on that release or roll back the current symlink.

Failed Docs Deploy

First checks:

• Confirm pnpm --filter ./docs build succeeds locally.
• Check that docs/dist/ was produced before packaging.
• Check docs environment secrets, especially DEPLOY_DOCS_PATH.
• Confirm the docs vhost points at the docs current symlink.

The docs site is static. PHP, Composer, Laravel migrations, and queue workers are not part of docs deployment.

Stale Content

If an editor changed content but visitors still see the old version:

php artisan cache:clear
php artisan statamic:stache:refresh
php please static:warm

Then check:

• the entry is published for the current site;
• the correct localized site was edited;
• the page URL matches the localized slug;
• static cache warming is enabled or was run for the affected environment.

404 Asset

First checks:

• Confirm the asset exists in the Statamic asset container.
• Confirm current/public/assets points to shared public assets.
• Confirm the file exists in shared public assets.
• Check whether the asset was migrated manually, uploaded through the Control Panel, or committed as a tracked public asset.

Avoid deleting shared assets while investigating. Missing shared files affect every release.

Form Submission Fails

First checks:

• Confirm Friendly Captcha keys are configured.
• Check recent Laravel logs for captcha verification errors.
• Confirm the Statamic form handle exists in resources/forms/.
• Confirm the mail transport and admin recipient are configured.
• Check queue workers if mail is queued in the current environment.

For local development, the Friendly Captcha token dev is accepted by the service.

Mail Not Sending

First checks:

• Check Laravel logs.
• Confirm the active mailer configuration.
• Confirm the admin address configuration.
• Check provider credentials in the private environment.
• Check queue workers if mail delivery is queued.

Do not publish provider dashboards, message traces, or recipient-specific details in public docs.

Locked or Broken Control Panel User

Runtime Statamic user account files live in the shared users/ directory on the server. Role and group definitions are versioned in the repository under resources/users/.

First checks:

• Confirm the user exists in the shared users directory.
• Confirm roles and groups still exist in the release.
• Use the project’s approved password reset or user repair procedure.

Do not publish account email addresses, reset links, or one-off access details in public docs.