Nginx error after Debian distribution upgrade: unknown directive rewrite_by_lua_block

Written by Claudio Kuenzler - 0 comments

Published on December 11th 2025 - Listed in Nginx Linux

---

After the distribution upgrade of a Linux machine from Bullseye (Debian 11) to Bookworm (Debian 12), the Nginx web server failed to start. The whole distribution upgrade itself failed due to the errors caused by the Nginx upgrade.

As it turns out, the LUA module got removed during the upgrade. Here's what happened and how to fix it.

Package upgrade failed

Typical distribution upgrade procedure. It all seemed to work fine - until the nginx package was upgraded.

root@debian:~# apt-get dist-upgrade
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
[...]
Dec 11 09:29:52 debian systemd[1]: Starting nginx.service - A high performance web server and a reverse proxy server...
Dec 11 09:29:52 debian nginx[2425050]: 2025/12/11 09:29:52 [emerg] 2425050#2425050: unknown directive "rewrite_by_lua_block" in /etc/nginx/luaheader.conf:3
Dec 11 09:29:52 debian nginx[2425050]: nginx: configuration file /etc/nginx/nginx.conf test failed
Dec 11 09:29:52 debian systemd[1]: nginx.service: Control process exited, code=exited, status=1/FAILURE
Dec 11 09:29:52 debian systemd[1]: nginx.service: Failed with result 'exit-code'.
Dec 11 09:29:52 debian systemd[1]: Failed to start nginx.service - A high performance web server and a reverse proxy server.
dpkg: error processing package nginx (--configure):
 installed nginx package post-installation script subprocess returned error exit status 1
[...]
Errors were encountered while processing:
 nginx
 libnginx-mod-http-headers-more-filter
 libnginx-mod-http-image-filter
 libnginx-mod-stream
 libnginx-mod-http-upstream-fair
 libnginx-mod-stream-geoip
 libnginx-mod-http-uploadprogress
 libnginx-mod-http-xslt-filter
 libnginx-mod-http-auth-pam
 libnginx-mod-http-geoip
 libnginx-mod-nchan
 libnginx-mod-http-ndk
 libnginx-mod-http-cache-purge
 libnginx-mod-http-echo
 libnginx-mod-http-subs-filter
 libnginx-mod-http-perl
 libnginx-mod-http-geoip2
 libnginx-mod-stream-geoip2
 libnginx-mod-http-dav-ext
 libnginx-mod-mail
 libnginx-mod-http-fancyindex
E: Sub-process /usr/bin/dpkg returned an error code (1)

Taking a closer look at the mentioned file /etc/nginx/luaheader.conf indeed uses the "rewrite_by_lua_block" and is included in multiple server contexts.

The rewrite_by_lua_block is part of the lua-nginx-module. This module is packaged in the libnginx-mod-http-lua package. Was this module not upgraded or installed?

Lua module removed

As it turns out, the libnginx-mod-http-lua package was not installed during the upgrade - even though it was installed before. To make this even more confusing, the symlink in /etc/nginx/modules-enabled was renamed from the suffix .conf to .removed. Nginx only enabled dynamic modules ending with .conf.

root@debian:/etc/nginx/modules-enabled# ls -la
total 28
[...]
lrwxrwxrwx 1 root root 61 Apr 20  2020 50-mod-http-image-filter.conf -> /usr/share/nginx/modules-available/mod-http-image-filter.conf
lrwxrwxrwx 1 root root 52 Apr 20  2020 50-mod-http-lua.conf.removed -> /usr/share/nginx/modules-available/mod-http-lua.conf
lrwxrwxrwx 1 root root 53 Apr 20  2020 50-mod-http-perl.conf -> /usr/share/nginx/modules-available/mod-http-perl.conf
[...]

Obviously with the lua module disabled, Nginx will not recognize the rewrite_by_lua_block snippet and will fail with an error.

root@debian:~# nginx -t
2025/12/11 09:31:40 [emerg] 2426763#2426763: unknown directive "rewrite_by_lua_block" in /etc/nginx/luaheader.conf:3
nginx: configuration file /etc/nginx/nginx.conf test failed

Fix: Re-Install lua module package, fix symlink

The fix is to install the (for whatever reason) missing module and then fix the symlink in /etc/nginx/modules-enabled:

root@debian:~# apt install  libnginx-mod-http-lua
root@debian:~# cd /etc/nginx/modules-enabled/
root@debian:/etc/nginx/modules-enabled# ln -s /usr/share/nginx/modules-available/mod-http-lua.conf 50-mod-http-lua.conf

root@debian:/etc/nginx/modules-enabled# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

root@debian:/etc/nginx/modules-enabled# rm 50-mod-http-lua.conf.removed
rm: remove symbolic link '50-mod-http-lua.conf.removed'? y

The config now works again, and the distribution-upgrade process can be successfully finished:

root@debian:~# apt-get dist-upgrade
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
[...]
Removing perl-modules-5.32 (5.32.1-4+deb11u4) ...
Removing python3-requests-toolbelt (0.10.1-1) ...
Removing python3-zope.component (5.1.0-1) ...
Removing python3-zope.event (4.4-3) ...
Removing python3-zope.hookable (5.1.0-1+b4) ...
Removing python3-zope.interface (5.5.2-1+b1) ...
Processing triggers for libc-bin (2.36-9+deb12u13) ...
Processing triggers for mailcap (3.70+nmu1) ...
Processing triggers for nginx (1.22.1-9+deb12u3) ...
Triggering nginx reload ...

Add a comment

Show form to leave a comment

Comments (newest first)

No comments yet.