Nginx now powers a staggering share of the web. According to long-running surveys of active sites, it sits behind roughly a third of all websites and an even larger slice of the busiest ones. That popularity comes with a catch: millions of people copy configuration snippets from blog posts, forums, and AI chatbots, paste them into production, and then wonder why their site returns 404s, leaks headers, or falls over under load. The mistakes below are the ones that show up again and again in support threads and post-mortems.
Skipping the Final Fallback in try_files
The try_files directive checks a list of paths in order and uses the last parameter as a fallback. That last parameter is not optional in practice. It should be a named location, a URI, or an explicit status like `=404`. Leave it out and Nginx has nowhere to go when nothing matches, which produces confusing internal errors or unexpected routing.
The classic broken pattern looks like `try_files $uri $uri/ /index.html` written without understanding what happens when `index.html` itself is missing. A safer habit is to always end with an explicit outcome, such as `try_files $uri $uri/ =404;` for static sites, or route to a named PHP location for dynamic apps. The official try_files documentation is short and worth reading once, properly.
Getting proxy_pass Trailing Slashes Wrong
This one causes more 404s than almost anything else. When proxy_pass includes a URI part, such as `proxy_pass Nginx replaces the matched location prefix with that URI. When it has no URI part, the full original request URI is passed through unchanged.
| Configuration | Request path | What upstream receives |
|---|---|---|
| `location /api/ { proxy_pass }` | `/api/users` | `/users` |
| `location /api/ { proxy_pass }` | `/api/users` | `/api/users` |
Neither is wrong. The mistake is not knowing which one you wrote. Pick a convention, document it, and test it with curl before shipping. The proxy_pass reference spells out the exact substitution rules.
Assuming add_header Inherits Everywhere
Headers set with add_header at the `server` block level are silently dropped inside any `location` block that defines its own `add_header`. This is inheritance by replacement, not by addition. People add a cache-control header in one location and accidentally lose their HSTS, X-Frame-Options, and CORS headers there.
In practice, the fix is either to repeat the security headers in each location or to use the `include` directive with a shared snippet file. The add_header documentation confirms the behavior, and it is a common gotcha even for experienced admins.
Using if Inside location Blocks
Nginx’s own community guidance is blunt: if is evil when used inside a `location` block. The directive creates an implicit nested configuration, and the results are famously unpredictable. Conditions that seem obvious, like checking a file exists, can behave differently than expected.
The official IfIsEvil page lists the safe uses, which are narrow. For most real problems, the right tools are map, try_files, or return. If you find yourself writing `if ($http_user_agent ~*…)`, stop and reach for a map block instead. It is evaluated once per request and behaves predictably.
Forgetting worker_processes auto
A default install often ships with `worker_processes 1;`. On a modern multi-core box, that leaves most of the CPU idle while one worker does all the work. Setting worker_processes auto; lets Nginx match the number of available cores, which is the recommended starting point in the core module docs.
The related mistake is over-tuning. People set worker connections to absurd values without raising the file descriptor limit, so the kernel caps them anyway. Check `worker_rlimit_nofile`, then set `worker_connections` to something the system can actually support.
Misordering server_name Directives
When several `server` blocks could match a request, Nginx picks a winner using a fixed order: exact names first, then leading wildcards, then trailing wildcards, then regular expressions in the order they appear, and finally the default server. Get that order wrong and traffic lands on the wrong virtual host.
A very common variant: someone adds a catch-all `server_name _;` block and expects it to be the default, but an earlier block with a matching regex wins instead. The server names guide explains the precedence clearly, and it is worth a reread whenever you add a new domain.
Leaving client_max_body_size at 1m
The default client_max_body_size is 1 megabyte. Upload a photo, a PDF, or a CSV and the client gets a 413 error that looks like a server bug. Raise it deliberately, per server or per location, and remember that PHP and your application framework may have their own limits that also need adjusting. The client_max_body_size reference confirms the default and the syntax.
Confusing root and alias
root appends the full request URI to the path. alias replaces the matched location prefix entirely. Mix them up and Nginx looks for files in paths that do not exist, producing mysterious 404s for assets that are clearly on disk.
If a location ends with a trailing slash, the alias should too. That symmetry matters more than most people realize. The alias documentation is terse but precise, and it is the fastest way to settle the argument.
Ignoring location Modifier Precedence
The location matching rules are not intuitive. Exact matches with `=` win outright. Then `^~` prefix matches. Then regex matches in file order. Then the longest plain prefix. Many configs work by accident until someone adds a regex location and quietly steals traffic from a prefix block.
| Modifier | Meaning | Priority |
|---|---|---|
| `=` | Exact match | Highest |
| `^~` | Prefix, skip regex | Second |
| `~` / `~*` | Regex, case-sensitive or not | Third, in order |
| none | Plain prefix | Lowest |
The location reference lays out the full algorithm. Reading it once prevents years of confusion.
Not Setting the Host Header to the Upstream
By default, Nginx does not forward the original Host header to a proxied backend. The upstream sees whatever Nginx sends, which can break virtual host routing, redirects, and cookie domains. The standard fix is a single line: `proxy_set_header Host $host;`. Most real deployments also want `X-Real-IP` and `X-Forwarded-For` so the backend can log the actual client address. The proxy_set_header reference covers the syntax and the common variables. (Nginx)
Editing Configs Without Testing Them
`nginx -t` takes about a second and catches syntax errors before they take a site down. Skipping it is the single most avoidable mistake on this list. A reload with a broken config fails, but a restart with a broken config can leave you with no running server at all.
The practical workflow is simple: edit, run `nginx -t`, reload with `nginx -s reload`, then check the error log. Keep a known-good copy of the config directory before big changes. It costs nothing and has saved countless weekends. (nginx documentation)
Forgetting to Tune Logging and Buffers
Two quieter mistakes cause real pain at scale. First, leaving the default access log format on a high-traffic site, which generates enormous files and disk pressure. Second, ignoring the buffer directives for proxied responses, so slow backends hold connections open longer than necessary.
A related habit worth building: when you need to capture what a page actually looks like for a bug report or a handoff, a quick screenshot on Windows or a screenshot on a Mac is faster than describing the error in prose. Visual evidence of a 502 page or a broken header panel ends arguments quickly.
Copying Snippets Without Understanding Them
The meta-mistake behind most of the others is pasting config from a random source and never reading it. Snippets age badly. They assume a directory layout, a PHP version, or a proxy setup that may not match yours. They also frequently include the `if` blocks and missing `try_files` fallbacks described above.
A better habit is to treat every pasted block as a draft. Read the directive docs for anything unfamiliar, test in a staging environment, and keep comments explaining why a block exists. Six months later, your future self will thank you.
Conclusion
Nginx rewards people who read the manual. Almost every mistake on this list traces back to a default that was never checked or a snippet that was never understood. The fixes are small: add a fallback to `try_files`, decide on a trailing-slash convention for `proxy_pass`, repeat headers where they are needed, avoid `if` inside `location`, set `worker_processes auto`, order `server_name` blocks deliberately, raise `client_max_body_size` when uploads are expected, keep `root` and `alias` straight, learn the location precedence table, forward the Host header, and always run `nginx -t` before reloading. None of these takes more than a few minutes. Together they turn a fragile config into one that behaves the same way every time.
FAQ
What is the most common nginx configuration mistake?
The most frequently reported one is a missing final fallback in try_files, which causes misrouting and confusing errors. Close behind is the `proxy_pass` trailing-slash confusion, which produces 404s because the upstream receives a different path than the author expected.
Why does my add_header rule stop working in one location?
Because add_header does not merge across levels. If a `location` block defines any `add_header`, it discards headers inherited from the parent `server` block. Repeat the headers in that location or pull them in with an `include` snippet.
Is using if inside a location block always wrong?
Not always, but it is wrong far more often than people assume. The safe uses are narrow, and the official guidance warns that `if` creates a nested configuration with surprising behavior. For most conditional logic, use map, try_files, or return instead.
Why do uploads fail with a 413 error?
The default client_max_body_size is 1 megabyte. Anything larger is rejected before it reaches your application. Raise the value in the relevant `server` or `location` block, and check that your application framework and PHP settings allow the same size.
How do I know which server block will handle a request?
Nginx matches in a fixed order: exact names, then leading wildcards, then trailing wildcards, then regex in file order, then the default server. If traffic lands somewhere unexpected, check whether a regex block is appearing earlier than you thought.
Do I need to restart nginx after every config change?
No. Run `nginx -t` to validate the syntax, then `nginx -s reload` to apply changes without dropping connections. A full restart is only needed for certain low-level changes, and it is riskier because a broken config can leave you with nothing running.
A final word on proxy buffering and timeouts: the defaults for `proxy_read_timeout` and the buffer sizes are tuned for small responses, and a backend that streams large files or holds long-poll connections will exhaust worker connections while looking healthy in the access log. Set `proxy_buffering off` deliberately for streaming endpoints, and raise timeouts only where the upstream genuinely needs them. Blanket changes hide the real problem. Similarly, `keepalive` to upstreams requires both `keepalive` in the upstream block and `proxy_http_version 1.1;` plus clearing the `Connection` header, or connections are reopened on every request. The upstream module docs spell this out, and the omission is invisible until load rises.
Finally, write configs for the person who inherits them. Comment non-obvious blocks, group related directives, and keep a short README beside the config directory recording which snippets are included where. A well-commented config is its own documentation, and it turns the next outage into a five-minute fix instead of an afternoon of archaeology.
