Using WordPress ‘graceful_fail’ PHP filter

The graceful_fail WordPress PHP filter allows you to handle errors more gracefully by providing custom error messages.


add_filter('graceful_fail', 'my_custom_error_handler');

function my_custom_error_handler($error_message) {
    // your custom code here
    return $error_message;


  • $error_message (string) – The default error message provided by WordPress.

More information

See WordPress Developer Resources: graceful_fail


Custom 404 Error Message

Customize the 404 error message when a page is not found.

add_filter('graceful_fail', 'my_custom_404_error_message');
function my_custom_404_error_message($error_message) {
    if (is_404()) {
        $error_message = 'Oops! The page you are looking for cannot be found.';
    return $error_message;

Custom Login Error Message

Customize the error message displayed when a user enters incorrect login credentials.

add_filter('graceful_fail', 'my_custom_login_error_message');
function my_custom_login_error_message($error_message) {
    if (is_wp_error($error_message)) {
        $error_message = 'Invalid username or password. Please try again.';
    return $error_message;

Custom Database Connection Error Message

Display a friendly error message when there is a problem connecting to the database.

add_filter('graceful_fail', 'my_custom_database_error_message');
function my_custom_database_error_message($error_message) {
    if (strpos($error_message, 'Error establishing a database connection') !== false) {
        $error_message = 'We are experiencing technical difficulties. Please try again later.';
    return $error_message;

Custom Permission Denied Message

Display a custom error message when a user does not have permission to access a certain area of the site.

add_filter('graceful_fail', 'my_custom_permission_denied_message');
function my_custom_permission_denied_message($error_message) {
    if (strpos($error_message, 'You do not have sufficient permissions') !== false) {
        $error_message = 'Sorry, you are not allowed to access this page.';
    return $error_message;

Custom File Upload Error Message

Provide a custom error message when there is an issue with uploading a file.

add_filter('graceful_fail', 'my_custom_file_upload_error_message');
function my_custom_file_upload_error_message($error_message) {
    if (strpos($error_message, 'The uploaded file exceeds the upload_max_filesize') !== false) {
        $error_message = 'The uploaded file is too large. Please upload a smaller file.';
    return $error_message;