Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more

Put server_names_hash_bucket_size in NGINX’s top-level http block, raise it to the next power of two named by the error, then run nginx -t and reload NGINX. If the message instead says it cannot build an optimal hash and offers server_names_hash_max_size, increase that maximum first when many names are configured.

Identify which hash problem you have

NGINX builds server-name hash tables when it starts and whenever it processes a configuration reload. The tables let it select the virtual server for an incoming Host name without scanning every server block. A configuration can therefore be syntactically valid yet fail at startup or reload while NGINX is constructing the hash.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Read the complete error before changing anything. The wording points to two different causes:

Error pattern Likely cause First change to make
could not build the server_names_hash followed by increase server_names_hash_bucket_size: 32 (or another value) At least one configured name is too long for the current bucket capacity. Set server_names_hash_bucket_size to the next power of two above the reported value.
could not build optimal server_names_hash followed by increase either server_names_hash_max_size: 512 or server_names_hash_bucket_size: 32 There are many names, so the selected table size is not efficient, or a long name is also present. Raise server_names_hash_max_size first, to a value near the number of configured names.

A hard “could not build” error can prevent NGINX from starting. An “optimal” warning may still allow it to run, but it signals a hash layout that NGINX considers inefficient. Treat both as configuration problems and test the full configuration before reloading.

#1 Best Overall
Sale
Compressed Air Duster,130000RPM Super Power Cordless Air Duster,Rechargeable Brushless Blower,3 Gear Adjustable Blower with LED Light,Dust Remover for Computer/House/Outdoor/Car
  • Powerful Turbo Fan:CAGIWIRU Electric Air Duster have reached speed up to 130000RPM,Can efficient remove dust and debris.With LED light and Three Adjustable Speed to meet with different cleaning tasks.
  • With Attached USB C Fasting Charging cable.Charing 3 hours,Enjoy up to 240 minutes of use on the lowest setting, For third speed can use for 25mins.with four charging options to meet with your needs.
  • Wide Application: attached 5 different nozzles,making it suitable for a variety of scenes, such as car,pet, pc, keyboards, and other electronic devices. It also serves for office and home clean duster.
  • Handy Design & Portable:Cordless air duster electric nozzle is Light weight and small size, design and comfortable to hold and space saving, convenient to carry around. You can put it in your room or inside the car without taking up space.
  • Economical &Reusable: Built durable materials with a long-lasting battery,our CAGIWIRU air duster it's a sustainable alternative to disposable air cans.

Where the directives belong

Both directives are valid only in the top-level http context. Put them inside the http { ... } block in the main configuration, not inside an individual server or location block.

http {
    server_names_hash_bucket_size 64;
    server_names_hash_max_size 1024;

    include       mime.types;
    include       /etc/nginx/conf.d/*.conf;
    # server { ... } blocks and other http settings
}

The main file is commonly named nginx.conf, but package layouts differ. Included files are part of the same configuration tree. A directive placed in a file that is not included, or placed under the wrong context, has no effect or causes an “directive is not allowed here” error.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Find the active configuration file

Ask the installed binary which prefix and configuration it uses:

nginx -V 2>&1

Inspect the output for the --conf-path option. Then inspect that file and every include it references. On a running system, the effective configuration can also be printed with:

nginx -T

The -T output includes the main file and expanded includes. Use it to verify that your hash directives appear inside the intended http block and to locate every server_name.

Fix a single long server name

NGINX’s documented example uses the name too.long.server.name.example.org. With a bucket size of 32, NGINX reports:

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
EVEO® Screen Cleaner Spray Kit (Streak-Free) TV Screen Cleaner for Smart TV, Lcd, LEd, Oled | Computer Screen Cleaner Spray and Wipe Microfiber Cloth - TV, Monitor, Laptop, iPad, Car - 6.7oz 1 Pack
  • Screen Cleaner is Your Screen’s New Bestfriend! - EVEO is proud to present a screen cleaner that’s perfectly suited for your TV. Meet your new screen cleaner, computer screen cleaner, laptop cleaner, iPad cleaner, Macbook,tv cleaner or any other electronic device. Our screen cleaner spray and wipe along with the included plush microfiber cloth, easily removes dust, fingerprints & other smudges on the screen’s surface. Clean effectively for a streak-free screen
  • Gentle on your Screens - Our screen cleaner spray and wipes is compatible to be used even for the most sensitive LCD, LED, CRT, and OLED screens in proper use. Be at ease knowing that this product is compatible with all the major brands: LG, SONY, Samsung, Sharp, iPad, iPhone, Android screens, Kindle, PC monitors - we’ve got you covered! Can be used as LCD screen cleaner, tv cleaner, smart tv screen cleaner, and more
  • Premium Super Soft Plush Microfiber Cloth - Included in this efficient screen cleaning kit. This screen cleaner spray and wipe has our signature plush microfiber cloth specially designed to comply with screens and monitors and leave them streak-free. Has been shown to effectively absorbs stubborn stains, zero streaks, and no fiber shedding. Always use this together with our screen cleaner for the best results
  • Easy-to-Use Screen Cleaner Kit + microfiber cleaning cloth - The EVEO Screen Cleaning Kit will easily be your new favorite tool when it comes to taking care of the things you love most, quick and easy solution for a streak-free screen. Simply screw on the sprayer gun on the screen cleaner bottle. Spray the cleaning liquid onto the microfiber cloth, then wipe the screen until desired cleanliness & shine is achieved.
  • Quality Screen Care Kit Worth Purchasing - Enjoy a convenient Screen Cleaner anytime, anywhere you need it. Your satisfaction is our top priority. We stand behind the quality of our products and that’s why, you shouldn’t be worrying at all. We manufacture the Best Screen Cleaner. and can be used for laptop cleaning kit, laptop screen cleaner, tv screen cleaner for smart tv. MacBook screen cleaner, monitor cleaner or screen cleaner spray for electronic devices with microfiber cleaning cloth
could not build the server_names_hash,
you should increase server_names_hash_bucket_size: 32

Change the value to the next power of two:

http {
    server_names_hash_bucket_size 64;
}

Use the value shown in your own error, not the example’s number. The usual progression is 32, 64, 128, 256 and so on. If the message names 64, use 128; if it names 128, use 256. NGINX’s documentation specifies increasing the bucket size to the next power of two.

Why a long name causes a hard failure

Exact names and wildcard names are stored in hash tables. A bucket must have enough capacity for the longest entry, including the internal bookkeeping NGINX uses. When one name cannot fit, NGINX cannot construct the table and aborts startup or the reconfiguration attempt.

Maxim Dounin, an NGINX maintainer, describes the limit directly: the value of server_names_hash_bucket_size limits the maximum length of a server_name used. He recommends sizing it for the maximum expected name plus additional space for two pointers. In practice, the error’s requested value and the next power-of-two rule provide the safe operational setting.

Check whether shortening is possible

Before increasing a global setting, inspect the names that caused it. Remove obsolete aliases, duplicate names and temporary migration hostnames when they are no longer needed. A shorter canonical hostname or a reduced alias list can solve the capacity problem without changing hash memory characteristics. Do not remove a name that clients, certificates or DNS records still require.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Fix a large collection of names

When many names are configured, NGINX may report:

could not build optimal server_names_hash,
you should increase either server_names_hash_max_size: 512
or server_names_hash_bucket_size: 32

For this form, increase server_names_hash_max_size first. The directive controls the maximum number of buckets NGINX may use while building the name table; its documented default is 512. Choose a value close to the number of configured names, then leave room for aliases added by the same deployment.

http {
    server_names_hash_max_size 1024;
}

There is no universal replacement number. Count the exact and wildcard names in the expanded configuration, select a practical upper bound, and retest. If NGINX still requests a larger bucket size, apply the bucket-size rule as a second change. Raising both directives immediately can hide which constraint was responsible and can allocate more hash-table space than necessary.

Rank #3
Sale
BladeHawks RGB Gaming Mouse Pad Extra Large Extended 31.5x12 Inch-Black | LED mouse pad with 14 lighting modes, covers keyboard & mouse, anti-slip rubber base, waterproof surface, USB powered
  • 【Large size】:Measuring 800 x 300 mm/ 31. 5×12 inches, which is wider and taller than others. Large mouse pad can perfectly fit your keyboard and mouse of any size, and there is also ample space for peripherals such as phones, tablets, etc.
  • 【LED backlight mouse pad】:Blade Hawks RGB mouse pad provides 7 static modes and 7 dynamic modes will give you the options you are looking for. Power-off memory function remembers the last lighting mode you selected. The super glow fiber Chroma will give you a colorful gaming setup that you want.
  • 【Anti-slip rubber base】:Made from Natural rubber, this gaming mousepad will firmly grip your desktop, allowing you to enjoy the ultimate precision in the games you are most passionate about. It also comes with a texture that enhances this ability even further.
  • 【Smooth and waterproof surface】: Micro-textured cloth surface, for extremely precise mouse control and a smooth movement. When liquid splashes on the gaming mouse pad, it forms water droplets and slides down. Will not delay your work or gameplay.
  • 【Plug and play】: This mouse and keyboard pad is powered by USB, plug and play, no driver required. One button control light modes. Press one time to change the lighting mode, press twice to change the brightness, press and hold about 3 seconds turn ON/OFF.

Count names in all included files

Do not count only the file you last edited. Names can be declared in virtual-host files, generated snippets and distribution-specific include directories. Use nginx -T, search its output for server_name, and account for every token after the directive. A single server block can contain several aliases, and each contributes to the hash.

Understand the two directives

Directive Context Documented default What it controls When to change it
server_names_hash_bucket_size size; http 32, 64 or 128, depending on processor cache-line size The capacity of each hash bucket and therefore the maximum server-name length that can fit. A long name triggers a message naming this directive, or NGINX still cannot build the table after the maximum size is increased.
server_names_hash_max_size size; http 512 The maximum number of buckets NGINX may allocate for the server-name hash. Many names produce an “optimal hash” message that offers this directive.

Bucket size is aligned with the processor’s cache-line size to reduce memory accesses during lookup. Consequently, an unnecessarily large bucket is not automatically an improvement. Keep it at the smallest power of two that accommodates the longest required name, and prefer increasing the maximum table size first when the error indicates a crowding problem.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Apply the change safely

  1. Capture the exact error. Record whether it names server_names_hash_bucket_size, server_names_hash_max_size, or both, and note the numeric values.
  2. Inspect the complete configuration. Run nginx -T or inspect the file reported by nginx -V. Find the longest name and estimate the total count, including aliases and included files.
  3. Choose one targeted edit. For one long name, add the bucket directive in http and move to the next power of two. For many names, raise server_names_hash_max_size first.
  4. Test before touching the running service. Run:
nginx -t

A successful test reports that the syntax is okay and the test is successful. If your installation uses a nondefault configuration path, pass it explicitly, for example nginx -t -c /path/to/nginx.conf, using the same path your service manager starts.

  1. Reload through the installed service manager. Use the mechanism that owns your NGINX process, such as systemctl reload nginx, the platform’s service nginx reload command, or nginx -s reload. A reload rebuilds the hash while applying the new configuration; a full stop and start is normally unnecessary after a successful test.
  2. Check the result. Review the NGINX error log and service status. Confirm that the reload completed and that the hash message did not recur.

If the test fails, do not reload. Correct the reported syntax, context or include-path problem, then run nginx -t again. If a reload fails after a successful test because of a service-manager or permission issue, the previous worker configuration generally remains active; inspect service logs before attempting a restart.

Common failure modes and recovery

The directive was added inside a server block

NGINX will reject a bucket or maximum-size directive outside http. Move it to the enclosing top-level block in the main configuration, or to an included file that is itself included from that block. Re-run nginx -t to verify the context.

The edited file is not included

Some installations load conf.d, sites-enabled or a generated configuration directory; others use a custom path. If the value does not appear in nginx -T, NGINX is not reading the file you changed. Edit the active file or add the correct include, then test again.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #4
Sale
Vaydeer Wrist Rest for Keyboard and Mouse, Computer Ergonomic Wrist Support Pad, Soft Memory Foam Arm Cushion for Desk, Palm Hand Office Laptop Typing
  • 【Softer and More Comfortable】Vaydeer wrist rest has unique diamond pattern, which is the combination of softness and aesthetics. The materials of wrist rest are improved into higher quality memory foam and covered with silky smooth lycra. The computer wrist rest makes you as comfortable and cushiony as like rest your wrists on clouds.
  • 【Ergonomic Wrist Saver】The wrist rests for keyboard and mouse comes with a 17.32×3.15×0.83 inch keyboard wrist pad and a 5.94×3.15×0.83 inch mouse wrist support. Based on ergonomic design, the unique concave shape is the perfect fit for your wrist joints. The wrist rest pad fits most computer keyboards and laptops, improve hand and wrist posture, release your wrist and arm stress.
  • 【Non-Slip Rubber Bottom】Featuring an anti-skid silicone base on the bottom, this wrist keyboard support stays firmly in place on your desk, preventing the padding from sliding around, ensuring stable and consistent wrist support during extended computer sessions.
  • 【Better Experience & Pain Relief】Our keyboard arm rest is beneficial to alleviate the soreness caused by direct contact and friction between your arm and a hard desk surface, reducing the risk of wrist fatigue or carpal tunnel. The soft texture of memory foam can evenly distribute the pressure around your wrists and provide good support with just enough give.
  • 【Helpful in Multiple Scenarios】Whether you're working, studying, writing, typing, gaming, this keyboard and mouse rest combo is an essential accessory to add comfort and support to your hands and wrists. It’s also a great gift for men, women, family, friend, coworker, gamer, teacher, etc.

The value was increased but the same long-name error remains

Check that the new value is a power of two greater than the number in the message and that no other included file overrides it later in the http block. Look for an even longer alias than the one you first noticed. If the error names a larger requested value, follow that request rather than repeatedly changing an unrelated setting.

The “optimal hash” warning persists

Count all names from the expanded configuration and increase server_names_hash_max_size toward that count. If the warning changes to a bucket-size request, then raise the bucket size to the next power of two. Remove stale aliases and redundant patterns where possible so future deployments do not require continually larger tables.

A reload appears successful but traffic is unchanged

Check the service manager’s status and NGINX’s error log, then verify that the process used the configuration you tested. A test against one file followed by a reload of a different service instance can produce this symptom. Compare the running process arguments with the nginx -V configuration path and use the matching reload command.

Server-name patterns and lookup cost

NGINX searches exact names before wildcard names. Exact names are therefore the best choice for frequently requested hosts when you know the complete hostname. Wildcard lookups are slower because NGINX searches by domain parts. Regular-expression names are tested sequentially and scale least well as the list grows.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  • Exact: use a complete hostname when the set of hosts is known and stable.
  • Wildcard: use only where a pattern genuinely represents many hosts; keep the pattern set small and intentional.
  • Regular expression: reserve for cases that cannot be expressed with exact or wildcard names, because sequential testing becomes more expensive as patterns accumulate.

These lookup characteristics do not replace the hash-size fix, but they explain why simply increasing values forever is poor configuration design. Consolidating unnecessary aliases and replacing broad patterns with explicit names can reduce both table pressure and lookup work.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Choosing values without over-sizing

Use the error and the configuration, not a copied number from another server. Defaults vary: the documented bucket default is 32, 64 or 128 according to processor cache-line size, while the documented maximum table size default is 512. A setting that is appropriate on one host may be excessive or insufficient on another.

Best Value
Sale
Under Desk Cable Management Tray No Drill, Metal Mesh Cable Management Under Desk with Clamp Mount, 2 Hole Cable Tray with Wire Management and Cord Organizer for Home Office Standing Desk
  • 【No Drill Mounted】Cable management tray can be assembled in as little as 3 minutes or less-simply. Side clips easily clampe the edge of desk, pass through the holes on the sides, and secure excess cables with baskets. Desk cable management supports inward or outward installation to meet your needs in different scenarios, and provides you with great convenience when collecting and organizing wires.
  • 【Rubber Pad Protects Desk】Wire organizer under desk built-in soft rubber pads on the clamp protect your desk from scratches, so you will not damage your furniture or office.
  • 【Sturdy and Beautiful】Cord management under desk is made of high-quality carbon steel and holds about 15 lbs. The wire basket has 2 holes on each side of the tray to enable your cables to pass freely. Cable baskets are suitable for desk thickness use from 0.4" to 2.4".
  • 【Space Saving & Keep Organized】Desk cable management tray holds all your power cords, outlet strips, USB hubs and computer transformers hidden from your feet, and the data cables will not enter the vacuum cleaner to keep your desk clean and tidy. Desk wire organizer is also suitable for use in the kitchen and outdoors.
  • 【Reduce Safety Risks】Cable tray under desk keeps all plugs away from your kids, no more worry about tripping. Using 2 holes wire tray saves extra space, helps you easily cabling and wire protection. The mesh design is not easy to accumulate dust, but avoids safety accidents caused by messy wires.
  • For a long name, start with the requested bucket value and select the next power of two.
  • For many names, start with a maximum size near the actual name count, then retest.
  • Keep the bucket as small as the longest required name permits because cache-aware sizing is part of NGINX’s design.
  • Change one directive at a time when the message offers alternatives, so the resulting behavior identifies the real constraint.
  • Document the reason for an unusually high value beside the directive, especially when names are generated automatically.

The hash is rebuilt at every startup and reconfiguration. A value that works today must still accommodate names added by the next deployment, so include expected aliases in your sizing decision without allocating an unnecessarily large bucket for hypothetical names.

A repeatable diagnostic checklist

  • Have you copied the complete error, including the requested number?
  • Is the directive inside the top-level http block?
  • Does nginx -T show the directive and every included server_name?
  • Is the problem one unusually long name or a large number of names?
  • For a long name, did you choose the next power of two?
  • For many names, did you try server_names_hash_max_size first?
  • Did nginx -t pass using the same configuration path as the service?
  • Did you reload with the service manager that owns the running process?
  • After reloading, are the service status and error log clear?

Worked examples

Example: one long hostname

An error asks for server_names_hash_bucket_size: 32. The configuration contains a long fully qualified hostname and only a few aliases. Add this to http:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
server_names_hash_bucket_size 64;

Run nginx -t. If it succeeds, reload NGINX. If the next startup message requests 128, use 128; do not keep 64 merely because it worked in a previous configuration.

Example: thousands of aliases

The message offers server_names_hash_max_size: 512 or server_names_hash_bucket_size: 32, and the names are ordinary in length but numerous. Count the names shown by nginx -T, remove retired aliases, then set a maximum near that count, such as:

server_names_hash_max_size 2048;

Test and reload. Only if NGINX then reports that a bucket cannot hold a name should you increase server_names_hash_bucket_size.

What not to do

  • Do not put the directive in a location block or inside an individual virtual host.
  • Do not reload after editing without first running nginx -t.
  • Do not assume a warning about an optimal hash requires a huge bucket; increase the maximum table size first when the configuration has many names.
  • Do not copy a value from a different machine without considering its longest name, name count and processor-dependent default.
  • Do not delete aliases solely to silence the error if those aliases are still published in DNS, certificates or client configuration.

Final decision rule

Use server_names_hash_bucket_size for capacity problems caused by a long individual name, and choose the next power of two above the value NGINX reports. Use server_names_hash_max_size first when the issue is a crowded table containing many names. In either case, make the change in the http block, verify the complete expanded configuration with nginx -t, and reload through the correct service manager so NGINX rebuilds its hashes.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.