How to resolve web server permissions for Matomo (Linux and Windows)

On-Premise

File and directory permissions are the most common issues when setting up or upgrading Matomo. If permissions are wrong, Matomo cannot create or write to the required directories and this leads to errors such as:

  • Unable to create directory.
  • Failed to write cache file.
  • Other Unable to write messages affecting the tmp or config.

All of these issues have the same root cause where the web server (or PHP process) lacks the necessary write permissions for Matomo’s directories. Permissions control which users and processes can read, write, or execute files. If Matomo’s web server or PHP process cannot write to required directories, it leads to errors and failed updates.

This guide explains what Matomo needs write access to, and provides step-by-step solutions for both Linux and Windows environments.

Directories that require write access

Matomo needs to create temporary files, cache templates, and update its configuration when settings change. These operations require the web server or PHP process to have write permissions to specific directories. Granting access too broadly (for example, to the entire Matomo folder) creates unnecessary security risks, so the safest and most effective approach is to limit write access only to the directories that Matomo actually needs, which are:

  • matomo/tmp (including tmp/templates_c, tmp/cache, tmp/assets)
  • matomo/config (for config.ini.php)
  • matomo/misc/user/
  • matomo.js and piwik.js

All other files and directories should remain read-only to the web server as it minimises exposure while ensuring Matomo functions correctly.

Before you start

The steps you need to follow to resolve permissions errors will depend on the operating system and web server you are running Matomo on:

  • Linux (Apache or Nginx): Most self-hosted Matomo installations use Linux with Apache or Nginx. If your server shows errors like Unable to write or Failed to create directory, and you connect with SSH and run commands like ls or sudo, go to the Linux section below.

  • Windows (IIS): If you are running Matomo on a Windows server with IIS, go to the Windows section below as the commands and permissions are different from Linux.

Linux: Permissions for Matomo directories

When fixing permissions on Linux, two key commands are used:

  • chown (change owner): sets which user and group own a file or directory. For Matomo, ownership must match the user that runs your web server or PHP process (for example www-data on Debian/Ubuntu or apache on CentOS/RHEL).
  • chmod (change mode): sets read, write, and execute permissions. The recommended setup is:
    • Directories: 755 (owner can write, others can read and execute).
    • Files: 644 (owner can write, others can read).
  • Avoid using chmod 777. While it makes files writable for everyone, it’s insecure and hides the real issue. Instead, adjust ownership with chown and apply correct permissions with chmod as shown below.

To resolve write errors on Linux, follow these steps in the order outlined below:

1. Find the web server/PHP user/

Check your web server config for user and group settings, or list file ownership. Use the correct path to your Matomo server, for example:

ls -l /var/www/html/matomo/tmp //Replace with your specific path

Note the user name listed for the files. Common user names are www-data (Debian/Ubuntu), apache (RHEL/CentOS), or nginx.

2. Set ownership

Replace www-data:www-data with the correct user and group from step 1. Use your specific path:

sudo chown -R www-data:www-data /var/www/html/matomo

3. Apply safe permissions

For directories:

sudo find /var/www/html/matomo/tmp -type d -exec chmod 755 {} \;

For file:

sudo find /var/www/html/matomo/tmp -type f -exec chmod 644 {} \;

For assets subdirectory:

sudo find /var/www/html/matomo/tmp/assets -type d -exec chmod 755 {} \;
sudo find /var/www/html/matomo/tmp/assets -type f -exec chmod 644 {} \;

4. Clear cached templates (safe)

Do not delete the actual tmp folder.

sudo rm -rf /var/www/html/matomo/tmp/templates_c/* \
             /var/www/html/matomo/tmp/cache/* \
             /var/www/html/matomo/tmp/assets/*

5. Reload web server

sudo systemctl reload nginx 2>/dev/null || \
sudo systemctl reload apache2 2>/dev/null || \
sudo systemctl reload httpd 2>/dev/null

When permissions are set correctly, Matomo will recreate any needed subfolders (like tmp/templates_c/d7/…) automatically, so it is not necessary to create them manually.

Example: Linux

  • To fix errors like unable to create d7 and failed to write cache file, identify the web server user, e.g. www-data.
  • Run these commands (replace www-data with the correct user):
sudo chown -R www-data:www-data /var/www/html/matomo/tmp /var/www/html/matomo/config
sudo find /var/www/html/matomo/tmp -type d -exec chmod 755 {} \;
sudo find /var/www/html/matomo/tmp -type f -exec chmod 644 {} \;
sudo rm -rf /var/www/html/matomo/tmp/templates_c/* /var/www/html/matomo/tmp/cache/* /var/www/html/matomo/tmp/assets/*

Reload the web server and refresh Matomo. The templates_c/d7/... folder and files will be recreated automatically with the correct permissions.

Windows: Permissions for Matomo directories

To resolve write errors on Windows, follow these steps in the order outlined below:

1. Identify the application identity

Check which account runs the site: the site’s Application Pool identity (for example IIS AppPool\MatomoAppPool), or the group IIS_IUSRS.

2. Grant Modify rights to required folders

Only the tmp and config directories need write access. Run the icacls commands from the command prompt with administrator privileges.

icacls "C:\inetpub\wwwroot\matomo\tmp" /grant "IIS_IUSRS:(OI)(CI)M" /T
icacls "C:\inetpub\wwwroot\matomo\config" /grant "IIS_IUSRS:(OI)(CI)M" /T

If your site uses a custom Application Pool identity, replace the placeholder below with the actual name:

icacls "C:\inetpub\wwwroot\matomo\tmp" /grant "<YourAppPoolIdentity>:(OI)(CI)M" /T
icacls "C:\inetpub\wwwroot\matomo\config" /grant "<YourAppPoolIdentity>:(OI)(CI)M" /T

Note on parameters:

  • (OI) indicates Object Inherit: permissions apply to files inside the folder.
  • (CI) indicates Container Inherit: permissions apply to subfolders.
  • M indicates Modify: allows reading, writing, and deleting files, but not changing ownership or permissions.

These parameters ensure Matomo can read and write in the required folders without giving unnecessary privileges.

3. Clear compiled templates and cache

Delete the contents (not the actual folders) of:

  • C:\inetpub\wwwroot\matomo\tmp\templates_c\*
  • C:\inetpub\wwwroot\matomo\tmp\cache\*
  • C:\inetpub\wwwroot\matomo\tmp\assets\*

4. Recycle the Application Pool

In IIS Manager, Restart the site’s Application Pool, then reload Matomo in your browser. The required subfolders will be recreated automatically if permissions are correct.

Correct permissions are essential for Matomo to function reliably. By ensuring only the tmp and config directories are writable, and applying the right ownership for your web server or IIS Application Pool, you can resolve common errors and maintain a secure setup. Read more on configuring Matomo for security.

Previous FAQ: How to configure ‘open_basedir’ for Matomo to enhance security?