nginx: "Unknown Directive" — Module Not Loaded (or Wrong Version)

nginx parsed your config and found a directive no loaded module provides. The fix is loading the module (dynamic .so or package reinstall), not editing the directive away — and a config test before reload prevents downtime.

What you'll see

Root causes

Module not compiled in or not loaded

Debian splits extras into packages (libnginx-mod-http-*, nginx-extras) and dynamic modules load via load_module. try_files is core, but gzip_static, headers-more, geoip, brotli need their module.

Version-dependent syntax

Newer directives (e.g. ssl_reject_handshake, certain map flags) don't exist in old nginx: the config is fine, the binary is ancient. nginx -v against the directive's docs decides.

Fix it

  1. Identify the directive and its owning module
    nginx -t 2>&1 | head -3 ; nginx -V 2>&1 | tr ' ' '\n' | grep -iE 'with-http|module' | head -20
  2. Install/load the module
    sudo apt install libnginx-mod-http-headers-more-filter   # or: load_module modules/ngx_http_x.so; at the top of nginx.conf
  3. Test before touching the live service
    sudo nginx -t && sudo systemctl reload nginx   # reload swaps workers without dropping connections
  4. Version-bound directive: upgrade nginx (not workaround the config)
    sudo apt install nginx   # or pin the distro nginx that includes the directive you need

Field note

nginx -t is free and reads the whole config tree: the error names the file, line, and directive — everything needed to fix it before any impact. A reload never applies a broken config: nginx validates first and keeps running the old workers on failure. Restarts are the risky path; prefer reload.

Common questions

Why does the identical config work on my other server?

Different build flags or module packages: nginx -V output differs between them. The directive isn't portable across binaries that lack its module — compare the module lists.

What is load_module and where does it go?

It loads a compiled dynamic module (.so). It must appear in the main context at the very top of nginx.conf — before any directive the module provides is used.

Related fixes

Ship it right the first time

Our most-documented failures, packaged as ready-to-ship starter kits: Docker, Kubernetes, and Terraform.

Browse the template store →

One-time. Yours to modify. Instant download from the NinjaOps template store.