Common Problems

types_hash errors

Depending on the server architecture, it's possible to get the following error:

could not build the types_hash, you should increase either types_hash_max_size: 1024 or types_hash_bucket_size: 32

Nginx uses hash tables to speed up certain tasks, usually the default value is sufficient but depending on the actual server config this error might be encountered. The solution is to do exactly what the error message suggests, by adding to nginx.conf the following:

# add this to the http context
types_hash_max_size: 1024;

## OR add this to the http context, don't need both
# types_hash_bucket_size: 32

Only some rules are being applied

Nginx only uses one location block when processing a request.

A direct concequence of this is that if, either directly or via include statemtents, directives are defined like so:

# Make sure js files are served with a long expire
location ~* \.js$ {
	add_header "section" "long expire"; # for illustration only
	expires 1y;
}

# Oh, and kill etags for js files
location ~* \.js$ {
	add_header "section" "no etags"; # for illustration only
	etag off;
}

the section headers are only to demonstrate which location blocks applied to a particular request.

Only ONE of these location blocks will be used:

$ curl -I "http://nginx.h5bp.dev/js/main.js"
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 23 Oct 2014 09:58:47 GMT
Content-Type: application/javascript; charset=utf-8
Content-Length: 1
Last-Modified: Tue, 29 Oct 2013 15:17:17 GMT
Connection: keep-alive
ETag: "526fd17d-1"
Expires: Fri, 23 Oct 2015 09:58:47 GMT
Cache-Control: max-age=31536000
section: long expire
Accept-Ranges: bytes

The way to achieve the desired effect is to consolidate all rules into one location block:

location ~* \.js$ {
	# Make sure js files are served with a long expire
	add_header "section" "long expire"; # for illustration only
	expires 1y;
	add_header "section" "no etags"; # for illustration only
	etag off;
}

Which would then yield:

$ curl -I "http://nginx.h5bp.dev/js/main.js"
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 23 Oct 2014 10:00:22 GMT
Content-Type: application/javascript; charset=utf-8
Content-Length: 1
Last-Modified: Tue, 29 Oct 2013 15:17:17 GMT
Connection: keep-alive
Expires: Fri, 23 Oct 2015 10:00:22 GMT
Cache-Control: max-age=31536000
section: long expire
section: no etags
Accept-Ranges: bytes

Cannot dynamically serve requests

It might be expected that a request for a file that does not exist will always reach the backend application - but this is not necessarily the case.

Using php as an example, here is a simple example config:

server {
	listen 80;
	server_name example.com;
	root /var/www/example.com;

	location / {
		try_files $uri $uri/ /index.php;
	}

    location ~ \.php$ {
		fastcgi_pass 127.0.0.1:9000;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
		include fastcgi_params;
    }
}

With the above config, a request for /css/main.css, assuming the file exists, would be served directly by nginx whereas a request for /application/user.css would be processed by php.

It is tempting to add h5bp's basic ruleset by simply appending it in the server context:

server {
	listen 80;
	server_name example.com;
	root /var/www/example.com;

	location / {
		try_files $uri $uri/ /index.php;
	}

    location ~ [^/]\.php(/|$) {
		fastcgi_split_path_info ^(.+?\.php)(/.*)$;
		if (!-f $document_root$fastcgi_script_name) {
				return 404;
		}

		fastcgi_pass 127.0.0.1:9000;
		fastcgi_index index.php;
		include fastcgi_params;
    }

	# ADDED
	include h5bp/basic.conf;
}

The result in this case would be /css/main.css, assuming the file exists, is served with headers defined by h5bp's basic ruleset whereas /application/user.css will be a 404. The reason for this is that H5bp's basic ruleset includes, for example:

location ~* \.(?:jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc)$ {
	expires 1M;
	access_log off;
	add_header Cache-Control "public";
}

Which will also capture any dynamic requests matching that url pattern and not hand the request to the php application in the event of an error.

There are 3 basic strategies to resolve this:

Define error_page in each location block

Modifying (all) location blocks as follows:

location ~* \.(?:jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc)$ {

	error_page 404 = /index.php;

	expires 1M;
	access_log off;
	add_header Cache-Control "public";
}

Will make Nginx pass requests for files that don't exist to the application.

Use prefix routing

Prefix routing is always preferred - if there is a common path for static files this can be used to reduce the scope of any included rules:

server {
	listen 80;
	server_name example.com;
	root /var/www/example.com;

	location / {
		try_files $uri $uri/ /index.php;
	}

    location ~ \.php$ {
		fastcgi_pass 127.0.0.1:9000;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
		include fastcgi_params;
    }

	# ADDED. Apply only to the css, js and images folder
	location ~ ^/(css|images|js)/ {
		include h5bp/basic.conf;
	}
}

Change to use a 404 front-controller

Instead of using try_files alone, change the server config such that the application is the 404 page:

server {
	listen 80;
	server_name example.com;
	root /var/www/example.com;

	try_files $uri $uri/ @app;
	error_page 404 = @app;

    location @app {
		include fastcgi_params;
		fastcgi_pass 127.0.0.1:9000;
		fastcgi_param   SCRIPT_FILENAME     $document_root/index.php;
		fastcgi_param   SCRIPT_NAME         $document_root/index.php;
		fastcgi_param   DOCUMENT_URI        /index.php;
		fastcgi_index index.php;
    }

	# ADDED.
	include h5bp/basic.conf;
}

with this kind of setup it's necessary to explicitly define the php filename.

In this way after nginx has tried to serve a (none existant) static file, it will pass the request to the php application successfully.

6.1 KiB Raw Blame History