Custom Error Page Settings

Custom Error Page Settings via NGINX Balancer

When an application returns an error, the application server normally displays its default error page. An NGINX load balancer can replace it with a custom page containing clearer instructions and contact information.
Tomcat default 404 error page
Example of the default Tomcat error page for a missing resource.
On this page

Open the NGINX Configuration

1Open the Config panel

In the platform dashboard, locate the NGINX load balancer in the environment and click Config.

NGINX balancer Config button
Open the configuration manager for the NGINX load balancer.

Create the Custom Error Page

2Open the conf.d directory

Navigate to /etc/nginx/conf.d and create or upload the custom error-page file.

Create or upload a custom error page
Create a new file or upload an existing page to /etc/nginx/conf.d.

The documentation example uses a simple error.html file:

<p><big><b>custom error page</b></big></p>
Example error.html file
Example content of the custom error.html file.

Update the Main NGINX Configuration

3Replace the included generated configuration

Open /etc/nginx/nginx-jelastic.conf, copy its content, and paste it into /etc/nginx/nginx.conf in place of the following include line:

include /etc/nginx/nginx-jelastic.conf;
Replace the nginx-jelastic.conf include line
Replace the include line with the copied generated configuration.
Maintenance note: Copying generated configuration into nginx.conf allows custom editing, but future topology changes may require reviewing the generated NGINX configuration again.

4Replace the default error-page settings

Inside the server section, use the following directives:

error_page 403 404 500 502 503 504 /error.html;
proxy_intercept_errors on;
NGINX custom error-page directives
Configure NGINX to intercept upstream errors and return error.html.

Configure Error Page Locations

Update the relevant location blocks as follows:

location /error.html {
    root   /etc/nginx/conf.d;
    internal;
}

location / {
    if ($cookie_SRVGROUP ~ group|common) {
        proxy_pass http://$cookie_SRVGROUP;
        error_page 403 404 500 502 503 504 = /error.html;
    }
    if ($cookie_SRVGROUP !~ group|common) {
        add_header Set-Cookie "SRVGROUP=$group; path=/";
    }
    proxy_pass http://default_upstream;
    add_header Set-Cookie "SRVGROUP=$group; path=/";
}

location @rescue {
    proxy_pass http://$cookie_SRVGROUP;
    error_page 500 502 503 504 = error.html;
}

location @recycle {
    proxy_pass http://default_upstream;
    add_header Set-Cookie "SRVGROUP=$group; path=/";
}
Custom error-page location settings
Adjust the location sections to route supported errors to the custom page.

Configure HTTPS Handling

For HTTPS websites, make the additional changes below. These steps are not required for HTTP-only environments.

5Edit ssl.conf

Add the following directives to the server section of /etc/nginx/conf.d/ssl.conf:

proxy_intercept_errors on;

location /error.html {
    root   /etc/nginx/conf.d;
}
Configure the ssl.conf file
Enable intercepted errors and define the custom-page location for HTTPS.

6Edit ssl.upstreams.inc

Update the relevant condition in /etc/nginx/conf.d/ssl.upstreams.inc:

if ($cookie_SRVGROUP ~ group|common) {
    proxy_pass http://$cookie_SRVGROUP;
    error_page 403 404 /error.html;
    error_page 500 502 503 504 = @resque;
}
Adjust ssl.upstreams.inc
Update the SSL upstream rules for custom 403, 404, and server-error handling.
The source configuration uses the named location @resque. Keep the spelling consistent with the named location defined in the active NGINX configuration.

Restart and Test NGINX

7Restart the NGINX balancer

Restart the NGINX load-balancer node or nodes to apply all configuration changes.

Restart NGINX balancer nodes
Restart the load balancer after saving the configuration.

8Test a missing page

Open a non-existing URL under the application domain and verify that NGINX returns the custom page.

Custom NGINX error page
The custom page is displayed instead of the application server’s default response.

Platform-Wide Error Pages

When the complete environment or the server containing the custom configuration is unreachable, the platform displays its own default error page.

Platform default environment error page
Platform-wide availability notifications cannot be replaced by an environment-level custom page.
Limitation: Environment owners cannot modify platform-wide notifications shown when the entire environment is stopped or unreachable.

What’s next?