W3cubDocs

/WordPress

wp_die( string|WP_Error $message = '', string|int $title = '', string|array|int $args = array() )

Kills WordPress execution and displays HTML page with an error message.

Description

This function complements the die() PHP function. The difference is that HTML will be displayed to the user. It is recommended to use this function only when the execution should not continue any further. It is not recommended to call this function very often, and try to handle as many errors as possible silently or more gracefully.

As a shorthand, the desired HTTP response code may be passed as an integer to the $title parameter (the default title would apply) or the $args parameter.

Parameters

$message

(string|WP_Error) (Optional) Error message. If this is a WP_Error object, and not an Ajax or XML-RPC request, the error's messages are used.

Default value: ''

$title

(string|int) (Optional) Error title. If $message is a WP_Error object, error data with the key 'title' may be used to specify the title. If $title is an integer, then it is treated as the response code.

Default value: ''

$args

(string|array|int) (Optional) Arguments to control behavior. If $args is an integer, then it is treated as the response code.

  • 'response'
    (int) The HTTP response code. Default 200 for Ajax requests, 500 otherwise.
  • 'link_url'
    (string) A URL to include a link to. Only works in combination with $link_text. Default empty string.
  • 'link_text'
    (string) A label for the link to include. Only works in combination with $link_url. Default empty string.
  • 'back_link'
    (bool) Whether to include a link to go back. Default false.
  • 'text_direction'
    (string) The text direction. This is only useful internally, when WordPress is still loading and the site's locale is not set up yet. Accepts 'rtl' and 'ltr'. Default is the value of is_rtl().
  • 'charset'
    (string) Character set of the HTML output. Default 'utf-8'.
  • 'code'
    (string) Error code to use. Default is 'wp_die', or the main error code if $message is a WP_Error.
  • 'exit'
    (bool) Whether to exit the process after completion. Default true.

Default value: array()

More Information

You can add a WP_Error object. If you’ve done so, you can add $data['title'] to the error object and it will automatically be taken as (default/overwriteable) title for the die page

Source

File: wp-includes/functions.php 

function wp_die( $message = '', $title = '', $args = array() ) {
	global $wp_query;

	if ( is_int( $args ) ) {
		$args = array( 'response' => $args );
	} elseif ( is_int( $title ) ) {
		$args  = array( 'response' => $title );
		$title = '';
	}

	if ( wp_doing_ajax() ) {
		/**
		 * Filters the callback for killing WordPress execution for Ajax requests.
		 *
		 * @since 3.4.0
		 *
		 * @param callable $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_ajax_handler', '_ajax_wp_die_handler' );
	} elseif ( wp_is_json_request() ) {
		/**
		 * Filters the callback for killing WordPress execution for JSON requests.
		 *
		 * @since 5.1.0
		 *
		 * @param callable $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_json_handler', '_json_wp_die_handler' );
	} elseif ( wp_is_jsonp_request() ) {
		/**
		 * Filters the callback for killing WordPress execution for JSONP requests.
		 *
		 * @since 5.2.0
		 *
		 * @param callable $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_jsonp_handler', '_jsonp_wp_die_handler' );
	} elseif ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) {
		/**
		 * Filters the callback for killing WordPress execution for XML-RPC requests.
		 *
		 * @since 3.4.0
		 *
		 * @param callable $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_xmlrpc_handler', '_xmlrpc_wp_die_handler' );
	} elseif ( wp_is_xml_request()
		|| isset( $wp_query ) &&
			( function_exists( 'is_feed' ) && is_feed()
			|| function_exists( 'is_comment_feed' ) && is_comment_feed()
			|| function_exists( 'is_trackback' ) && is_trackback() ) ) {
		/**
		 * Filters the callback for killing WordPress execution for XML requests.
		 *
		 * @since 5.2.0
		 *
		 * @param callable $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_xml_handler', '_xml_wp_die_handler' );
	} else {
		/**
		 * Filters the callback for killing WordPress execution for all non-Ajax, non-JSON, non-XML requests.
		 *
		 * @since 3.0.0
		 *
		 * @param callable $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_handler', '_default_wp_die_handler' );
	}

	call_user_func( $function, $message, $title, $args );
}

Uses

Uses Description
wp-includes/load.php: wp_is_jsonp_request()

Checks whether current request is a JSONP request, or is expecting a JSONP response.
wp-includes/load.php: wp_is_xml_request()

Checks whether current request is an XML request, or is expecting an XML response.
wp-includes/functions.php: wp_die_jsonp_handler

Filters the callback for killing WordPress execution for JSONP requests.
wp-includes/functions.php: wp_die_xml_handler

Filters the callback for killing WordPress execution for XML requests.
wp-includes/functions.php: wp_die_json_handler

Filters the callback for killing WordPress execution for JSON requests.
wp-includes/load.php: wp_is_json_request()

Checks whether current request is a JSON request, or is expecting a JSON response.
wp-includes/load.php: wp_doing_ajax()

Determines whether the current request is a WordPress Ajax request.
wp-includes/query.php: is_trackback()

Determines whether the query is for a trackback endpoint call.
wp-includes/query.php: is_feed()

Determines whether the query is for a feed.
wp-includes/query.php: is_comment_feed()

Is the query for a comments feed?
wp-includes/functions.php: wp_die_ajax_handler

Filters the callback for killing WordPress execution for Ajax requests.
wp-includes/functions.php: wp_die_xmlrpc_handler

Filters the callback for killing WordPress execution for XML-RPC requests.
wp-includes/functions.php: wp_die_handler

Filters the callback for killing WordPress execution for all non-Ajax, non-JSON, non-XML requests.
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.

Used By

Used By Description
wp-includes/sitemaps/class-wp-sitemaps-renderer.php: WP_Sitemaps_Renderer::check_for_simple_xml_availability()

Checks for the availability of the SimpleXML extension and errors if missing.
wp-includes/class-wp-recovery-mode.php: WP_Recovery_Mode::handle_exit_recovery_mode()

Handles a request to exit Recovery Mode.
wp-includes/class-wp-recovery-mode.php: WP_Recovery_Mode::handle_cookie()

Handles checking for the recovery mode cookie and validating it.
wp-includes/class-wp-recovery-mode-link-service.php: WP_Recovery_Mode_Link_Service::handle_begin_link()

Enters recovery mode when the user hits wp-login.php with a valid recovery mode link.
wp-includes/class-wp-fatal-error-handler.php: WP_Fatal_Error_Handler::display_default_error_template()

Displays the default PHP error template.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::handle_load_themes_request()

Load themes into the theme browsing/installation UI.
wp-admin/press-this.php: wp_load_press_this()
wp-includes/comment.php: wp_check_comment_flood()

Checks whether comment flooding is occurring.
wp-admin/includes/ajax-actions.php: wp_ajax_get_post_thumbnail_html()

Ajax handler for retrieving HTML for the featured image.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_inactive_widgets()

Ajax handler for removing inactive widgets.
wp-includes/class-wp-customize-nav-menus.php: WP_Customize_Nav_Menus::ajax_load_available_items()

Ajax handler for loading available menu items.
wp-includes/class-wp-customize-nav-menus.php: WP_Customize_Nav_Menus::ajax_search_available_items()

Ajax handler for searching available menu items.
wp-admin/includes/media.php: wp_media_attach_action()

Encapsulates the logic for Attach/Detach actions.
wp-admin/includes/class-file-upload-upgrader.php: File_Upload_Upgrader::__construct()

Construct the upgrader for a form.
wp-admin/includes/class-wp-screen.php: WP_Screen::get()

Fetches a screen object.
wp-admin/includes/theme-install.php: install_theme_information()

Display theme information in dialog box form.
wp-admin/includes/ms.php: _access_denied_splash()

Displays an access denied message when a user tries to view a site’s dashboard they do not have access to.
wp-admin/includes/ms.php: check_upload_size()

Determine if uploaded file exceeds space quota.
wp-admin/includes/class-wp-theme-install-list-table.php: WP_Theme_Install_List_Table::prepare_items()
wp-admin/includes/plugin-install.php: install_plugin_information()

Display plugin information in dialog box form.
wp-admin/includes/upgrade.php: wp_check_mysql_version()

Checks the version of the installed MySQL binary.
wp-admin/includes/user.php: edit_user()

Edit user settings based on contents of $_POST
wp-admin/includes/post.php: post_preview()

Saves a draft or manually autosaves for the purpose of showing a post preview.
wp-admin/includes/post.php: write_post()

Calls wp_write_post() and handles the errors.
wp-admin/includes/post.php: edit_post()

Update an existing post with values provided in $_POST.
wp-admin/includes/post.php: bulk_edit_posts()

Process the post data for the bulk editing of posts.
wp-admin/includes/ajax-actions.php: wp_ajax_save_widget()

Ajax handler for saving a widget.
wp-admin/includes/ajax-actions.php: wp_ajax_upload_attachment()

Ajax handler for uploading attachments
wp-admin/includes/ajax-actions.php: wp_ajax_image_editor()

Ajax handler for image editing.
wp-admin/includes/ajax-actions.php: wp_ajax_set_post_thumbnail()

Ajax handler for setting the featured image.
wp-admin/includes/ajax-actions.php: wp_ajax_date_format()

Ajax handler for date formatting.
wp-admin/includes/ajax-actions.php: wp_ajax_time_format()

Ajax handler for time formatting.
wp-admin/includes/ajax-actions.php: wp_ajax_wp_remove_post_lock()

Ajax handler for removing a post lock.
wp-admin/includes/ajax-actions.php: wp_ajax_dismiss_wp_pointer()

Ajax handler for dismissing a WordPress pointer.
wp-admin/includes/ajax-actions.php: wp_ajax_add_menu_item()

Ajax handler for adding a menu item.
wp-admin/includes/ajax-actions.php: wp_ajax_add_meta()

Ajax handler for adding meta.
wp-admin/includes/ajax-actions.php: wp_ajax_add_user()

Ajax handler for adding a user.
wp-admin/includes/ajax-actions.php: wp_ajax_closed_postboxes()

Ajax handler for closed post boxes.
wp-admin/includes/ajax-actions.php: wp_ajax_hidden_columns()

Ajax handler for hidden columns.
wp-admin/includes/ajax-actions.php: wp_ajax_update_welcome_panel()

Ajax handler for updating whether to display the welcome panel.
wp-admin/includes/ajax-actions.php: wp_ajax_menu_get_metabox()

Ajax handler for retrieving menu meta boxes.
wp-admin/includes/ajax-actions.php: wp_ajax_wp_link_ajax()

Ajax handler for internal linking.
wp-admin/includes/ajax-actions.php: wp_ajax_menu_locations_save()

Ajax handler for menu locations save.
wp-admin/includes/ajax-actions.php: wp_ajax_meta_box_order()

Ajax handler for saving the meta box order.
wp-admin/includes/ajax-actions.php: wp_ajax_menu_quick_search()

Ajax handler for menu quick searching.
wp-admin/includes/ajax-actions.php: wp_ajax_get_permalink()

Ajax handler to retrieve a permalink.
wp-admin/includes/ajax-actions.php: wp_ajax_sample_permalink()

Ajax handler to retrieve a sample permalink.
wp-admin/includes/ajax-actions.php: wp_ajax_inline_save()

Ajax handler for Quick Edit saving a post from a list table.
wp-admin/includes/ajax-actions.php: wp_ajax_inline_save_tax()

Ajax handler for quick edit saving for a term.
wp-admin/includes/ajax-actions.php: wp_ajax_widgets_order()

Ajax handler for saving the widgets order.
wp-admin/includes/ajax-actions.php: wp_ajax_dashboard_widgets()

Ajax handler for dashboard widgets.
wp-admin/includes/ajax-actions.php: wp_ajax_logged_in()

Ajax handler for Customizer preview logged-in status.
wp-admin/includes/ajax-actions.php: _wp_ajax_add_hierarchical_term()

Ajax handler for adding a hierarchical term.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_comment()

Ajax handler for deleting a comment.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_tag()

Ajax handler for deleting a tag.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_link()

Ajax handler for deleting a link.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_meta()

Ajax handler for deleting meta.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_post()

Ajax handler for deleting a post.
wp-admin/includes/ajax-actions.php: wp_ajax_trash_post()

Ajax handler for sending a post to the Trash.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_page()

Ajax handler to delete a page.
wp-admin/includes/ajax-actions.php: wp_ajax_dim_comment()

Ajax handler to dim a comment.
wp-admin/includes/ajax-actions.php: wp_ajax_add_link_category()

Ajax handler for adding a link category.
wp-admin/includes/ajax-actions.php: wp_ajax_add_tag()

Ajax handler to add a tag.
wp-admin/includes/ajax-actions.php: wp_ajax_get_tagcloud()

Ajax handler for getting a tagcloud.
wp-admin/includes/ajax-actions.php: wp_ajax_get_comments()

Ajax handler for getting comments.
wp-admin/includes/ajax-actions.php: wp_ajax_replyto_comment()

Ajax handler for replying to a comment.
wp-admin/includes/ajax-actions.php: wp_ajax_edit_comment()

Ajax handler for editing a comment.
wp-admin/includes/ajax-actions.php: wp_ajax_fetch_list()

Ajax handler for fetching a list table.
wp-admin/includes/ajax-actions.php: wp_ajax_ajax_tag_search()

Ajax handler for tag search.
wp-admin/includes/ajax-actions.php: wp_ajax_wp_compression_test()

Ajax handler for compression testing.
wp-admin/includes/ajax-actions.php: wp_ajax_imgedit_preview()

Ajax handler for image editor previews.
wp-admin/includes/ajax-actions.php: wp_ajax_oembed_cache()

Ajax handler for oEmbed caching.
wp-admin/includes/ajax-actions.php: wp_ajax_autocomplete_user()

Ajax handler for user autocomplete.
wp-admin/includes/bookmark.php: wp_link_manager_disabled_message()

Outputs the ‘disabled’ message for the WordPress Link Manager.
wp-admin/includes/bookmark.php: edit_link()

Updates or inserts a link using values provided in $_POST.
wp-admin/includes/ms-deprecated.php: wpmu_checkAvailableSpace()

Determines if the available space defined by the admin has been exceeded by the user.
wp-admin/includes/class-wp-terms-list-table.php: WP_Terms_List_Table::__construct()

Constructor.
wp-admin/includes/file.php: validate_file_to_edit()

Makes sure that the file that was requested to be edited is allowed to be edited.
wp-admin/includes/comment.php: edit_comment()

Update a comment with values provided in $_POST.
wp-admin/includes/class-custom-image-header.php: Custom_Image_Header::step_2()

Display second step of custom header image page.
wp-admin/includes/class-custom-image-header.php: Custom_Image_Header::step_2_manage_upload()

Upload the file to be cropped in the second step.
wp-admin/includes/class-custom-image-header.php: Custom_Image_Header::step_3()

Display third step of custom header image page.
wp-admin/includes/class-custom-image-header.php: Custom_Image_Header::admin_page()

Display the page based on the current step.
wp-admin/includes/ms.php: confirm_delete_users()
wp-admin/includes/class-custom-background.php: Custom_Background::handle_upload()

Handle an Image upload for the background image.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::wp_die()

Custom wp_die wrapper. Returns either the standard message for UI or the Ajax message.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::setup_theme()

Start preview and customize theme.
wp-includes/theme.php: switch_theme()

Switches the theme.
wp-includes/pluggable.php: wp_redirect()

Redirects to another page.
wp-includes/pluggable.php: check_ajax_referer()

Verifies the Ajax request to prevent processing requests external of the blog.
wp-includes/class-wp.php: WP::parse_request()

Parse request to find correct WordPress query.
wp-includes/load.php: wp_check_php_mysql_versions()

Check for the required PHP version, and the MySQL extension or a database drop-in.
wp-includes/load.php: wp_maintenance()

Die with a maintenance message when conditions are met.
wp-includes/load.php: wp_set_wpdb_vars()

Set the database table prefix and the format specifiers for database table columns.
wp-includes/load.php: wp_not_installed()

Redirect to the installer if WordPress is not installed.
wp-includes/functions.php: wp_send_json()

Send a JSON response back to an Ajax request.
wp-includes/functions.php: dead_db()

Load custom DB error or display WordPress DB error.
wp-includes/functions.php: wp_nonce_ays()

Display “Are You Sure” message to confirm the action being taken.
wp-includes/functions.php: do_feed()

Load the feed template from the use of an action hook.
wp-includes/class-wp-ajax-response.php: WP_Ajax_Response::send()

Display XML formatted responses.
wp-includes/option.php: wp_protect_special_option()

Protects WordPress special option from being modified.
wp-includes/revision.php: _show_post_preview()

Filters the latest content for preview from the post autosave.
wp-includes/ms-functions.php: maybe_add_existing_user_to_blog()

Add a new user to a blog by visiting /newbloguser/{key}/.
wp-includes/ms-load.php: ms_not_installed()

Displays a failure message.
wp-includes/ms-load.php: ms_site_check()

Checks status of current blog.
wp-includes/ms-deprecated.php: wpmu_admin_do_redirect()

Redirect a user based on $_GET or $_POST arguments.
wp-includes/wp-db.php: wpdb::bail()

Wraps errors in a nice header and footer and dies.
wp-includes/wp-db.php: wpdb::print_error()

Prints SQL/DB error.
wp-includes/class-wp-customize-widgets.php: WP_Customize_Widgets::wp_ajax_update_widget()

Updates widget settings asynchronously.
wp-includes/comment.php: wp_allow_comment()

Validates whether this comment is allowed to be made.

Changelog

Version Description
5.5.0 The $text_direction argument has a priority over get_language_attributes() in the default handler.
5.3.0 The $charset argument was added.
5.1.0 The $link_url, $link_text, and $exit arguments were added.
4.1.0 The $title and $args parameters were changed to optionally accept an integer to be used as the response code.
2.0.4 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/wp_die