Introduction

While working on a project, I was challenged by a question from a client saying, "Can we customize the error page?". When he was talking about the error page, he was mainly referring to the one you get when you try to access a page that doesn't exist:

My first reaction was

And then I decided to dig further and see what we can do with it!

Changing the error text

The first option we have is to customize the text, which is possible by adding a text message called APEX.ERROR.PAGE_NOT_AVAILABLE.

This message will be used in the default error page generated by APEX to replace the default message.

To be fair, I found this solution in this discussion on the Oracle APEX Discussion Forum.

Changing the whole page

But wait, can we replace the page completely? The answer is yes, it is possible but it requires a little more work than the text message solution!

Oracle APEX Instance level configuration

First we need to change the Unhandled Errors parameter to "Return HTTP 400" under Manage Instance - Security.

You will probably wonder if it is safe not to choose the default value. The best answer is that the parameter help text says:

From a security standpoint, it is often better to not display these messages and error codes to the end user and simply return a HTTP 400 (Bad Request) error code to the client browser.

By changing this value, if you try again to display a page that does not exist, you will see the default ORDS error page.

And so, we changed this parameter and now we have a new generic page that doesn't look any better than the previous one. No, if you inspect your browser, you will see that the main change is that the status of the request is now 400.

Configuring the custom page

According to the ORDS documentation, you can define a custom error path by running the following command

ords --config /path/to/conf config set error.externalPath /path/to/error/pages/folder/

Finally, you need to create an HTML file under /path/to/error/pages/folder/ called 400.html. The file is called 400.html because it will be used for HTTP status 400, you can define another file for 401, 404, 500, etc.

After doing this, I was able to display my custom error page while navigating to a broken link.

Conclusion

I hope you like this post and it will help you to design some nice error pages for your APEX applications!