Troubleshooting and other resources

Troubleshooting

A collection of links with issues and how to potentially solve them.

Local environment-related (LAMP or Drupal)

Apache

• If you get any errors on Apache restart, you can debug with:

  systemctl status apache2.service

• Sometimes you need to check if the webserver can run a command. An example of testing if the user www-data can use pdftk (substitute with your web server user and command):

  sudo -H -u www-data bash -c 'pdftk --version'

Safeguard against breaking php.ini changes

As modifications of the php.ini might break PHP (and therefore also Apache), it is recommended to make a backup (with timestamp) before running any commands that might change the php.ini, including direct edits:

sudo cp /etc/php/7.3/apache2/php.ini /etc/php/7.3/apache2/php.ini.$(date -d "today" +"%Y-%m-%dT%H-%M").bak

To restore the backup (with prompt before overwrite):

sudo cp -i /etc/php/7.3/apache2/php.ini.[put-timestamp-here].bak /etc/php/7.3/apache2/php.ini

To see the latest modifications side-by-side with line numbers:

sdiff -l /etc/php/7.3/apache2/php.ini /etc/php/7.3/apache2/php.ini.[put-timestamp-here].bak | cat -n | grep -v -e '($'

The same approach can be used with other files that might affect your system and you need to revert, like the .bashrc file. 

To backup your current .bashrc file:

cp ~/.bashrc ~/.bashrc.bak

Ubuntu

• After editing .bashrc commands return 'command could not be located because '/bin' is not included in the PATH' - Ask Ubuntu
• Many issues are due to not having root permissions for a folder, for example [ubuntu] [SOLVED] Can't put files in the trash.
  While changing the "owner" to the current user is a sufficient solution on a one-user developer machine, as shown there, more elegant would be to create a group of users and assign them the right permissions.
• Having trouble that seems irresolvable with a specific package? Try removing it (do a search on how to do it properly) and reinstall it.
• Ubuntu, terminal not opening - Ask Ubuntu but first How To Switch Between TTYs Without Using Function Keys In Linux
• python - Errors when installing python3-dev on Ubuntu 20.04 - Super User

Composer

• composer require error: can't delete default.services.yml - Drupal Answers
• Diagnosing composer package conflicts installing Drupal console | alex-sansom.info
• Uncaught Error: Class 'ComposerAutoloaderInit' not found - Stack Overflow

Drupal

• Common Drupal Problems - Solutions Included | Chromatic
  For example the infamous message "The provided hostname is not valid for this server".
  In your local.settings.php add:

  /**
   * Trusted host configuration.
   *
   * See full description in default.settings.php.
   */
  $settings['trusted_host_patterns'] = array(
    '^.+$',
  );
  

• 400 Bad Request is most likely due to an incorrect domain syntax. The most common mistake is the use of an underscore in the locally used domain name, as we tend to use it a lot in filenames without problems.
• Drupal 8 "Mismatched entity and/or field definitions" | DrupalEasy
  After updating modules that interact with entities.
• 8 - Unable to install the XYZ module since it requires the A module - Drupal Answers
  Message after an unsuccessful config import.
• Site UUID in source storage does not match the target storage
  Message after an unsuccessful config import.
• Recent log messages: Attempting to re-run cron while it is already running. Try to solve by Release cron lock.
• How to fix "The following module is missing from the file system..." warning messages
• Config x depends on x that will not exist after import - Drupal Answers

When running out of disk space

df -h # Check remaining available disk space.
du -sh /* | sort -h # List folders and files in ascending size.
du -sh /var/* | sort -h # Pinpointing the big folder (example).
du -sh /var/log/* | sort -h # Continue until the cause is found.

• How to Check Disk Space in Linux {df and du Commands}
• Linux find largest file in directory recursively using find/du - nixCraft
• A Complete Guide to Managing Log Files with Logrotate - Better Stack Community
• 20.04 - Big /var/log/journal? - Ask Ubuntu
• How to get size of mysql database? - Stack Overflow
• MySQL Bin Files Eating Lots of Disk Space - nixCraft
• 8 - Watchdog file growing out of control - Drupal Answers
• PostgreSQL: Show size of all databases - makandra dev

MySQL

How To Reset Your MySQL or MariaDB Root Password on Ubuntu 20.04 | DigitalOcean

Error log

Access recent log messages (watchdog) without Drupal UI access

The log messages list can normally be accessed at admin/reports/dblog if the core dblog module is enabled. You can use drush watchdog:show in case you do not have admin access OR you get:
The website encountered an unexpected error. Please try again later.

Follow the error log

cd /var/log/apache2 # Optionally us nginx instead of apache2.
ls # Identify the log to follow
tail -f error.log # Optionally replace error.log with another log to follow.

Tip: Press Enter a couple of times to distinguish one output from the previous before refreshing the page in your browser.

Logging arrays with logger (D8)

To log array data in some readable format.

How to empty (truncate) Log files in Linux | ComputingForGeeks

truncate -s 0 logfile

Get system info on a remote server through SSH only, without any help

There is no Graphical User Interface (GUI) to interact with the server, so all operations should be done through a terminal, aka command-line interface (CLI). After a connection has been established, we would like to know some basics of the system we entered. This can be useful if we take over an existing server that we know nothing about.

Check what permissions you have

As many issues are due to lacking permissions, check first what sudo commands you are allowed to run on a remote server with:

sudo -l -U your-username

permissions - How do I find out if I am sudoer? - Unix & Linux Stack Exchange

Know on what Linux OS we are running

How to check os version in Linux command line. Use:

cat /etc/os-release

Get the web directory

To be able to navigate (cd) to a web directory, we have to know first its location. Use:

httpd -S

or

apachectl -S

Now you are able to navigate (cd) into the indicated Main DocumentRoot. It also provides you the Apache username and the group name that it belongs to. You need those if you need to change file and folder permissions. Think for example of the sites/default/files folder that often needs to change its permissions.

Alternatively, look for directories containing www:

find / -type d -name www 2> /dev/null

The 2> /dev/null option will eliminate permission error messages when not doing this as the root user. Instead of www, you can also search for html. Or sites-enabled and then inside the default file, look for the DocumentRoot.

Check both if Composer is available and to see other webserver component versions

If your permissions are set correctly and Composer is installed, you should be able without using sudo to use:

composer diag

Check if Git is available

git --version

Always use tar, never zip when transferring files to or from the server

Ideally, using Git and Composer, there should be no need to use SFTP to get files onto the server. In case you have to use this last resort, make sure to upload a tar (not a zip) as this leaves folder and file permissions intact. Put it in the correct folder (mkdir) and untar with:

tar -xvf filename

System-related

Giant steps have been made by Ubuntu and manufacturers to have drivers available out-of-the-box for the most common hardware components on both desktops and laptops. Most laptops nowadays can run Ubuntu without issues.

Many Linux users are part of an Open Source community and tend to share their experiences regarding issues on Q&A fora like Ask Ubuntu (part of StackExchange). Using your favorite search engine with the words "Ubuntu 18" and the issue that you experience, will most of the time solve your problems. This is also mainly due to the fact that most suggestions consist of terminal commands that on a known Ubuntu version will give predictable results.

Another bottleneck is having only one big computer brand offering their laptops with Ubuntu preinstalled, probably due to the marketing strategy of proprietary OS vendors. That means that in most cases the installation of Ubuntu should be performed by the users themselves. This is however well documented and easier than an installation of Windows or Mac if they would not be preinstalled.

If coming from Windows, always try if all hardware is working as it should (touchpad, audio, webcam, Bluetooth, wifi, etc.).

• Boot from USB (configurable in the BIOS), test if your hardware works, and then proceed with the permanent install if satisfactory. You can then overwrite your existing Windows OS or proceed with the dual boot as described below.
• If you intend to keep Windows install a Dual Boot where Ubuntu "lives" happily alongside the already present Windows. Turning on your machine, you can then choose which OS to use, Ubuntu or Windows.

Apart from some hardware components not working as expected, most other issues are due to system changes that you made to accomplish something. Sometimes an issue seems unrelated to a change and might manifest only after a reboot or when you need a certain application that does not load. The rule of thumb is:

When experiencing new issues in Ubuntu, think of the latest system change you made and revert that change.

Obviously, that includes backing up the old configuration in a place where you can reach it independently (USB or Google drive). If you are stuck with a system that won't boot, start in recovery mode and in the terminal: 

sudo nano /path/to/your/modified/file

Change the content back to its original value, save and restart your machine.

Other resources

Similar info about a local Drupal development environment.

• Drupal tools for developers | Drupalship
• The Simplest Path to a Drupal Local Environment | Lullabot (macOS)