Troubleshooting and recovery

Installation returns an error#

Confirm web and CLI PHP versions/extensions, supported MySQL, database connectivity and migrations. Keep APP_DEBUG=false publicly; inspect restricted application/server logs rather than exposing exception pages. Check write access for storage/ and bootstrap/cache/. The document root must be public/.

Page loads without styling#

Confirm public/build and its manifest exist. A release archive includes them; a source install needs npm ci and npm run build. Check asset responses and the canonical APP_URL. After a release, clear stale configuration/views with php artisan optimize:clear and follow your normal host cache workflow.

Signup is unavailable#

Check Registration for a deliberate closure, configured name/domain rules, current required terms and verification mail. With enabled Turnstile, a key or hostname change requires a fresh real-key test. An unavailable/unverified enabled integration blocks signup until corrected or explicitly disabled.

Emails are missing#

Check Email delivery for inherited/override transport status, sender verification, credentials and TLS/connectivity. Separate provider acceptance from inbox confirmation. For watched replies, check worker supervision, shared environment, subscriptions and current forum access. Investigate failed jobs before retries.

A member cannot see a forum#

Use Member access inspection for the actual member, groups, scoped rules and denies. Check bans and paid expiry where relevant. Test direct URLs/search as that account. Do not diagnose using an administrator who sees more content.

Theme or plugin breaks public pages#

Administration remains independent of public theme/plugin boot. Activate Default or run php artisan forum:theme default. Disable the offending plugin there, or use php artisan forum:plugins:disable / FORUM_PLUGINS_ENABLED=false for global recovery. Review version/dependency/migration status before re-enabling.

Migration or upgrade failed#

Freeze writes and preserve logs/state. MySQL DDL may have partially succeeded. Do not clear ledger records, run migrate:fresh, or point old code at a new schema. Follow the update recovery path with the pre-update matching bundle/code.

Ask for help#

Use the support community. Include version, host/PHP/MySQL, affected path, expected/actual result and sanitized error context. Remove credentials, application keys, member content and private file paths from screenshots/logs. Installation and hosting forums are linked from Get started.