Fixing SSI Directive Processing Errors in Legacy Code

I recently had some trouble deploying an SSI website on a new Apache install. Unfortunately, some of my pages were not working; they all threw the same, generic an error occurred while processing this directive error. As I was fixing the issues, I realised that a few of these steps are not well documented. Here’s what I did when fixing SSI errors in my Apache install. Hopefully, some of these steps will help you too. I have updated my tutorial on Multilingual Web Pages with Server Side Includes to reflect this post.

Check your server configuration

Firstly, Apache must be told to permit SSI. Open up your Apache configuration file, httpd.conf, and check that you have the following line uncommented.

LoadModule include_module libexec/apache24/mod_include.so

If you don’t know where your httpd.conf is located, here are a few of the more common ones. You’ll have to search for the location on your own OS if it isn’t listed below.

• UNIX
• DragonFly BSD, FreeBSD: /usr/local/etc/apache24/httpd.conf
• OpenBSD: /var/www/conf/httpd.conf
• macOS: /etc/apache2/httpd.conf
• GNU/Linux
• Arch, CentOS, RHEL: /etc/httpd/conf/httpd.conf
• Debian, OpenSUSE, Ubuntu: /etc/apache2/httpd.conf

Once you have changed this file, restart your Apache service.

Check .htaccess

Most users are likely using .htaccess to manage local site configurations. This is the standard used by scripts and programmes such as WordPress, as it does not involve altering the global Apache configuration.

Use the lines below in your .htaccess file to enable SSI for that directory.

Options +Includes
AddType text/html .shtml
AddHandler server-parsed .shtml
AddOutputFilter INCLUDES .shtml
DirectoryIndex index.shtml index.html index.htm index.php

If you want to be able to include SSI commands in standard .html or .htm files, then change AddHandler server-parsed .shtml to AddHandler server-parsed.html.

Please note that you will still need the httpd.conf changes mentioned above for these to work.

Check for legacy statements

Finally, you need to make sure that your SSI directives are appropriate for the release of Apache that you’re using. This may also apply to NGINX and IIS, where necessary.

The primary culprit of processing errors with legacy errors seems to be conditional expressions, especially when variables are involved. The following legacy code may work on some versions and configurations of Apache, but it is not recommended.

<!--#if expr"QUERY_STRING = /lang=en/"-->
    <!--#include virtual="en.html"-->
<!--#endif-->

On my latest installation, this legacy code would not work. Instead, the expression must be updated as follows.

<!--#if expr"%{QUERY_STRING} ~= /lang=en/"-->
    <!--#include virtual="en.html"-->
<!--#endif-->

Now the code will function as intended. You can review the complete list of expressions that are considered valid by Apache here.

Concluding Fixing SSI Directive Processing Errors

If you have followed my previous tutorial on Multilingual Pages with Server Side Includes, you may need to update your code to reflect these changes.

As always, drop a comment below or join my Discord server if you have any comments or questions.