Resolving “nginx: [warn] could not build optimal variables_hash” Nginx Error

Introduction

You’ve made some changes to Nginx, and did a syntax check or restarted/reloaded, you might have been greeted with this.

nginx: [warn] could not build optimal variables_hash, you should increase either variables_hash_max_size: 1024 or variables_hash_bucket_size: 64; ignoring variables_hash_bucket_size

What does this mean? The Nginx documentation has the following to say https://nginx.org/en/docs/hash.html

To quickly process static sets of data such as server names, map directive’s values, MIME types, names of request header strings, nginx uses hash tables. During the start and each re-configuration nginx selects the minimum possible sizes of hash tables such that the bucket size that stores keys with identical hash values does not exceed the configured parameter (hash bucket size). The size of a table is expressed in buckets. The adjustment is continued until the table size exceeds the hash max size parameter. Most hashes have the corresponding directives that allow changing these parameters, for example, for the server names hash they are server_names_hash_max_size and server_names_hash_bucket_size.

The hash bucket size parameter is aligned to the size that is a multiple of the processor’s cache line size. This speeds up key search in a hash on modern processors by reducing the number of memory accesses. If hash bucket size is equal to one processor’s cache line size then the number of memory accesses during the key search will be two in the worst case — first to compute the bucket address, and second during the key search inside the bucket. Therefore, if nginx emits the message requesting to increase either hash max size or hash bucket size then the first parameter should first be increased.

Nginx uses hash tables for static data so that it can easily look up data quickly for configuration values and parameters. The error above simply means that Nginx has run out of space to store data within the hash tables.

Resolution

The resolution is quite simple, as the error says, you need to increase two configuration options server_names_hash_max_size and server_names_hash_bucket_size.

• The default for variables_hash_max_size is 1024
• The default for variables_hash_bucket_size is 64

You’ll want to change variables_hash_max_size first, before changing variables_hash_bucket_size.

Normal Nginx

Edit /etc/nginx/nginx.conf and find the http { section and add the following to it.

variables_hash_max_size 2048;
variables_hash_bucket_size 64;

GridPane Nginx

You have two options, you can create the file /etc/nginx/conf.d/hash-table.conf and add the below config

or

You can add the below config to /etc/nginx/extra.d/http-context.conf

variables_hash_max_size 2048;
variables_hash_bucket_size 64;

Change Log

• 12/11/2024 – Updated GridPane Nginx section to include /etc/nginx/extra.d/http-context.conf as another possible location.