BookStack Code Mirror - website/blob - content/docs/admin/debugging.md

   1 +++
   2 title = "Debugging Errors"
   3 description = "How to find the cause of issues in BookStack"
   4 date = "2017-01-01"
   5 type = "admin-doc"
   6 +++
   7
   8
   9 When using BookStack, especially when initially setting it up or after updating, you may come across some errors. While we try to reduce these as much as possible and make them helpful sometimes you may come across a bland "An error has occurred" message. This is to prevent any potentially sensitive information being shown to all users.
  10
  11 This page details how you can find out more information about errors you may face and the resolutions to common problems we often see.
  12
  13 - [Error Log File](#error-log-file)
  14 - [Debug View](#debug-view)
  15 - [Common Issues & Resolutions](#common-issues--resolutions)
  16     - [Blank White Screen on Access](#blank-white-screen-on-access)
  17     - [No Styles and Large Icons on Access](#no-styles-and-large-icons-on-access)
  18     - [Failing Database or Auth System Credentials](#failing-database-or-auth-system-credentials)
  19     - [Dynamic Elements Not Working](#dynamic-elements-not-working)
  20     - [Broken Links or No Images After APP_URL Change](#broken-links-or-no-images-after-app_url-change)
  21 - [Submitting Issues](#submitting-issues)
  22
  23 ---
  24
  25 ### Error Log File
  26
  27 On a common installation, an error log can be found at the path `storage/logs/laravel.log`, relative to the top-level folder of your BookStack installation files.
  28 For instances installed using our Ubuntu installation scripts, this is commonly located at `/var/www/bookstack/storage/logs/laravel.log`.
  29 If the `laravel.log` file does not exist the `storage/logs` directory may not be writable by the server.
  30
  31 In some cases an error may be thrown before or after BookStack handles a request. These will typically show as very plain error pages
  32 without any BookStack header bar or styling. In these cases you'll want to refer to your webserver error logs instead.
  33
  34 - Common Apache error log path on Ubuntu: `/var/log/apache2/error.log`
  35 - Common Nginx error log path on Ubuntu: `/var/log/nginx/error.log`
  36
  37 You will likely need privileged access to read these files. For example `sudo tail -n 100 /var/log/apache2/error.log`.
  38
  39 If using an alternative hosting method, such as docker container, please refer to the documentation provided by that method/container.
  40
  41 ---
  42
  43 ### Debug View
  44
  45 _**NOTE: When debugging is enabled it's possible for visitors to see private credentials used in the BookStack or server configuration. Ensure debugging is only enabled when your instance is not accessible by others. Remember to disable debugging before restoring access.**_
  46
  47 To enable full error displaying edit the `.env` file, in the application root directory, and add or update the `APP_DEBUG` option to `APP_DEBUG=true`. Errors will now be displayed in full with details of where it occurred. Remember to revert this change once you have found the issue so that the detailed error information is hidden from visitors.
  48
  49 ---
  50
  51 ### Common Issues & Resolutions
  52
  53 The below lists some of the common issues we see, when it comes to installing & maintaining BookStack, and their usual resolutions.
  54
  55 ##### Blank White Screen on Access
  56
  57 A completely blank screen, when attempting to access your BookStack instance, is commonly due to system/folder permission issues.
  58 Check that webserver user has read/write access to the `bootstrap/cache`, `storage` and `public/uploads` folders within your BookStack install.
  59 On a common Ubuntu install this can usually be done by running `sudo chown -R www-data:www-data bootstrap/cache storage public/uploads` from within the BookStack install folder. We have further guidance on filesystem permissions [on our page here](/docs/admin/filesystem-permissions/).
  60
  61 If you don't believe this is due to permissions, and you have nothing in the `storage/logs/laravel.log` file as detailed above, you'd next want to look at your webserver error logs which can commonly be found within `/var/log/nginx/` or `/var/logs/apache2/`.
  62
  63 ##### No Styles and Large Icons on Access
  64
  65 If the page loads, but shows large icons and appears broken, it generally means the system is generating incorrect paths to some required files
  66 or those files do not exist.
  67
  68 - Check that the `APP_URL` option is set in your `.env` file and ensure it matches the URL you're accessing BookStack on (Including the "https://" or "http://" component).
  69 - Check that you're using the `release` code branch. If you cloned the project without a branch flag, or downloaded the files from GitHub, you may be using the development branch files which does not include some of these required files.
  70
  71 ##### Failing Database or Auth System Credentials
  72
  73 If you've used a password in the `.env` file which you are sure is correct, but authentication fails for that service, it may be due to
  74 special characters being handled different in the `.env` configuration. Ensure that any such passwords or config options are wrapped in quotes. For example:
  75
  76 ```txt
  77 DB_PASSWORD="hunter#2@"
  78 ```
  79
  80 ##### Dynamic Elements Not Working
  81
  82 If certain dynamic elements, like dropdown menus or section tabs, are not working it often indicates that there
  83 may be other scripts interfering with BookStack's JavaScript code.
  84
  85 - Check that the `APP_URL` option is set in your `.env` file and ensure it matches the URL you're accessing BookStack on (Including the "https://" or "http://" component).
  86 - If using Cloudflare, with its DNS proxy feature, ensure that ["Rocket Loader" is disabled](https://developers.cloudflare.com/fundamentals/speed/rocket-loader/enable/).
  87 - Check your "Custom HTML Head Content" customization setting and, if existing, temporarily remove any code in this setting to ensure it's not interfering.
  88 - Use your browser developer tools to check the development console, and see if any errors exist.
  89
  90 ##### Broken Links or No Images After APP_URL Change
  91
  92 BookStack will store absolute URL paths for some content, such as images, in the database.
  93 If you change your base URL for BookStack this can be problematic.
  94 This command will essentially run a find & replace operation on all relevant tables in the database.
  95 Be sure to take a database backup for running this command.
  96
  97 ```bash
  98 # Searches for <oldUrl> and replaces it with <newUrl>
  99 php artisan bookstack:update-url <oldUrl> <newUrl>
 100
 101 # Example:
 102 php artisan bookstack:update-url http://docs.example.com https://demo.bookstackapp.com
 103 ```
 104
 105 ---
 106
 107 ### Submitting Issues
 108
 109 If you have found the cause of the issue, and it is not an issue with your particular setup, you can submit it on the [GitHub issues page](https://github.com/BookStackApp/BookStack/issues). Please include as much information as possible when creating an issue along with steps detailing how to replicate it so the bug can be fixed by a developer.