Whether you've encountered a White Screen of Death, a generic "internal server error" message, or some other broken behavior – sometimes it can be hard to work out what's gone wrong with your Waterhole installation. Here are a few things to try:
Check the logs. These may contain more information about what's going wrong:
Waterhole logs in storage/logs
Web server logs (e.g. /var/log/nginx/error.log)
PHP-FPM logs (e.g. /var/log/php8.x-fpm.log)
Turn on debug mode. Waterhole has a debug mode which you can turn on to enable detailed error reporting in the browser. However, you should only use this for debugging on a development server – do NOT turn this on in production, as you risk exposing sensitive configuration values to the public.
Clear the application cache. Likewise, sometimes old or corrupted data in the Waterhole/Laravel cache can cause outdated assets and translations to be served. Run php artisan waterhole:cache:clear to clear the Waterhole cache, and php artisan cache:clear to clear the Laravel cache.
Use the latest version of Waterhole. Bugs and other issues can be fixed with newer versions of the software, so it's always a good idea to keep up to date.
Check your configuration. Go through your .env file and config directory, as well as the configuration documentation, to make sure everything is correct.
Re-run optimizations. If you're using certain optimizations in your production environment, you need to re-run them on each deploy, otherwise old code will be cached. Any changes you make to the .env file will not take effect until the configuration cache is refreshed.
Disable local customizations. Comment out any local customizations you've made in your app's WaterholeServiceProvider to see if you can isolate a problem.
Disable extensions. Sometimes extensions can be the culprit. You can either remove them with the composer remove command or disable them temporarily by opting out of package discovery.
If you're confident that you've found an issue with Waterhole itself – not a problem on your end, or with an extension – please lodge it in our issue tracker by following the instructions on Reporting Bugs.