How to verify Varnish VCL configuration

Written by Claudio Kuenzler - 0 comments

Published on August 14th 2025 - last updated on August 15th 2025 - Listed in Varnish

---

When Varnish doesn't start due to an error in the VCL, it will (in most cases) write the reason of the error as a syslog event. 

On modern Linux distributions this can be seen with journalctl -u varnish:

root@debian13:~# journalctl -u varnish
[...]
Aug 14 06:06:47 debian13 systemd[1]: Started varnish.service - Varnish Cache, a high-performance HTTP accelerator.
Aug 14 06:06:47 debian13 varnishd[1849]: Info: Working directory not mounted on tmpfs partition
Aug 14 06:06:47 debian13 varnishd[1849]: Working directory not mounted on tmpfs partition
Aug 14 06:06:47 debian13 varnishd[1849]: Error:
Aug 14 06:06:47 debian13 varnishd[1849]: Message from VCC-compiler:
Aug 14 06:06:47 debian13 varnishd[1849]: Cannot read file 'includes/probes.vcl' (No such file or directory)
Aug 14 06:06:47 debian13 varnishd[1849]: ('/etc/varnish/default.vcl' Line 8 Pos 9)
Aug 14 06:06:47 debian13 varnishd[1849]: include "includes/probes.vcl";
Aug 14 06:06:47 debian13 varnishd[1849]: --------#####################-
Aug 14 06:06:47 debian13 varnishd[1849]: Running VCC-compiler failed, exited with 2
Aug 14 06:06:47 debian13 varnishd[1849]: VCL compilation failed
Aug 14 06:06:47 debian13 systemd[1]: varnish.service: Main process exited, code=exited, status=2/INVALIDARGUMENT
Aug 14 06:06:47 debian13 systemd[1]: varnish.service: Failed with result 'exit-code'.
Aug 14 06:06:47 debian13 systemd[1]: varnish.service: Scheduled restart job, restart counter is at 5.
Aug 14 06:06:47 debian13 systemd[1]: varnish.service: Start request repeated too quickly.
Aug 14 06:06:47 debian13 systemd[1]: varnish.service: Failed with result 'exit-code'.
Aug 14 06:06:47 debian13 systemd[1]: Failed to start varnish.service - Varnish Cache, a high-performance HTTP accelerator.

But let's be honest: This is too late. If you restart Varnish and it runs into an error then you've just caused a downtime.

Note: In production environments you should consider reloading the VCL (using systemctl reload varnish or directly invoking the varnishreload script) instead of restarting Varnish.

It's much better to verify the VCL before restarting (or reloading) Varnish. 

This can be done using the varnishd command with the -C argument. It compiles the given VCL file (with the -f argument). Obviously if there are syntax or other errors, the compilation fails. The output will let you know:

root@debian13:~# varnishd -C -f /etc/varnish/default.vcl
Message from VCC-compiler:
Cannot read file 'includes/probes.vcl' (No such file or directory)
('/etc/varnish/default.vcl' Line 8 Pos 9)
include "includes/probes.vcl";
--------#####################-

Running VCC-compiler failed, exited with 2
VCL compilation failed

Conveniently this is the exact same output as seen during the restart attempt above. 

You can therefore verify your VCL's in an automated pipeline or similar before pushing to the Varnish servers.

Add a comment

Show form to leave a comment

Comments (newest first)

No comments yet.