Common Nginx Issues and Solutions: Startup Errors, Load Balancing, Caching, and Performance Tuning

1. Nginx Startup Failure

When logs show

0.0.0.0:80 failed (10013: An attempt was made to access a socket in a way forbidden by its access permissions)

, it indicates port 80 is already in use.

2. Weight and ip_hash

In an upstream block, weight gives a server higher request priority, while ip_hash binds a client to a specific server. down marks a server offline. weight and ip_hash cannot be used together.

3. Nginx + Tomcat Load Balancing and Multi‑Domain Same‑Port Forwarding

Define multiple upstream blocks, each named after the target domain, and configure corresponding server blocks with proxy_pass http://<domain>. Use domain names in upstream for proper DNS resolution, especially for AJAX requests.

4. Installing Nginx on Linux

Prerequisites:

yum install gcc pcre pcre-devel zlib zlib-devel openssl openssl-devel

. Extract source, configure with ./configure --prefix=..., then make and make install. Manage service with /usr/local/nginx/sbin/nginx, -s stop, -s reload, and check status via netstat -autlp|grep nginx.

5. Logging Request Time

Add "$request_time" to log_format to record response time.

6. Cache‑Control Header Values

Common directives: no-cache, no-store, private, public, max-age, Expires. Combine them to control browser and proxy caching behavior.

7. Static vs. Dynamic Compression

Static compression pre‑compresses files (e.g., 1.html.gz) and serves them with add_header Content-Encoding gzip. Dynamic compression uses gzip on with parameters like gzip_min_length, gzip_buffers, gzip_comp_level, and gzip_types. Disable gzip for old IE versions with gzip_disable "MSIE [1-6]\." and enable gzip_vary on.

8. Unknown Directive Errors

Errors such as unknown directive "if($args" usually mean the PCRE library is missing; install PCRE and OpenSSL, then rebuild Nginx with --with-pcre=....

9. Fixing PCRE Build Issues

Copy PCRE headers and libraries to /usr/local/include/pcre, ensure the path in --with-pcre has no trailing slash, and remove the ./configure --disable-shared line from the generated Makefile if it causes failures.

10. Passing Real Client IP

Use proxy_set_header Host $host; and proxy_set_header X-Forwarded-For $remote_addr; in reverse‑proxy configurations.

11. Common if Syntax Mistakes

Missing space between if and the opening parenthesis or lacking PCRE support can trigger unknown directive errors.

12. Adding Custom Cache Header

Example:

add_header X-Cache '$upstream_cache_status from $server_addr';

13. Enabling Cache for Specific HTTP Statuses

Use proxy_cache_valid 200 304 20m; to cache successful responses.

14. Request URI Variables

$request_uri

returns the full request URI; $uri$is_args$args gives the normalized path with query string.

15. Placement of rewrite

rewrite

directives must be inside a location block; placing them in server causes 404 errors.

16. Debugging Nginx with GDB

Add -g to compilation flags in auto/cc/conf (e.g., ngx_compile_opt="-c -g") and rebuild to enable source‑level debugging.

17. High‑Concurrency Tuning

Adjust kernel parameters in /etc/sysctl.conf (e.g., net.core.somaxconn = 262144, net.ipv4.tcp_tw_reuse = 1) and file descriptor limits in /etc/security/limits.conf ( * soft nofile 65535, * hard nofile 65535) to support thousands of simultaneous connections.

18. Custom Log Format

Define

log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent "$http_referer" "$http_user_agent" "$gzip_ratio" "$upstream_addr - $upstream_status - $upstream_cache_status' "cacheKey:\"$host:$server_port$request_uri\"';

19. if Group Limit

Regular‑expression groups in an if condition cannot exceed nine; split logic into multiple if statements if needed.

20. Error Page Redirection

Define an internal location (e.g., @hhvm_error_to_php) and use error_page 500 502 503 504 = @hhvm_error_to_php; to handle upstream errors.

21. Resolving "aborted" Access Issues

When Nginx reload fails, kill the process and restart; outdated shared libraries (e.g., libz.so.1) can cause reload to be ineffective.