wp_die() – Function | Developer.WordPress.org

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

$messagestring|WP_Erroroptional

Error message. If this is a WP_Error object, and not an Ajax or XML-RPC request, the error’s messages are used.

Default:''

$titlestring|intoptional

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:''

$argsstring|array|intoptional

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: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

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 $callback Callback function name.
		 */
		$callback = 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 $callback Callback function name.
		 */
		$callback = apply_filters( 'wp_die_json_handler', '_json_wp_die_handler' );
	} elseif ( wp_is_serving_rest_request() && wp_is_jsonp_request() ) {
		/**
		 * Filters the callback for killing WordPress execution for JSONP REST requests.
		 *
		 * @since 5.2.0
		 *
		 * @param callable $callback Callback function name.
		 */
		$callback = 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 $callback Callback function name.
		 */
		$callback = 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 $callback Callback function name.
		 */
		$callback = 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 $callback Callback function name.
		 */
		$callback = apply_filters( 'wp_die_handler', '_default_wp_die_handler' );
	}

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

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_die_ajax_handler’, callable $callback ): Filters the callback for killing WordPress execution for Ajax requests.
apply_filters( ‘wp_die_handler’, callable $callback ): Filters the callback for killing WordPress execution for all non-Ajax, non-JSON, non-XML requests.
apply_filters( ‘wp_die_jsonp_handler’, callable $callback ): Filters the callback for killing WordPress execution for JSONP REST requests.
apply_filters( ‘wp_die_json_handler’, callable $callback ): Filters the callback for killing WordPress execution for JSON requests.
apply_filters( ‘wp_die_xmlrpc_handler’, callable $callback ): Filters the callback for killing WordPress execution for XML-RPC requests.
apply_filters( ‘wp_die_xml_handler’, callable $callback ): Filters the callback for killing WordPress execution for XML requests.

Uses	Description
wp_is_serving_rest_request()`wp-includes/functions.php`	Determines whether WordPress is currently serving a REST API request.
wp_is_jsonp_request()`wp-includes/load.php`	Checks whether current request is a JSONP request, or is expecting a JSONP response.
wp_is_xml_request()`wp-includes/load.php`	Checks whether current request is an XML request, or is expecting an XML response.
wp_is_json_request()`wp-includes/load.php`	Checks whether current request is a JSON request, or is expecting a JSON response.
wp_doing_ajax()`wp-includes/load.php`	Determines whether the current request is a WordPress Ajax request.
is_trackback()`wp-includes/query.php`	Determines whether the query is for a trackback endpoint call.
is_feed()`wp-includes/query.php`	Determines whether the query is for a feed.
is_comment_feed()`wp-includes/query.php`	Is the query for a comments feed?
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 4 more Show less

Used by	Description
wp_ensure_editable_role()`wp-admin/includes/ms.php`	Stop execution if the role can not be assigned by the current user.
WP_Sitemaps_Renderer::check_for_simple_xml_availability()`wp-includes/sitemaps/class-wp-sitemaps-renderer.php`	Checks for the availability of the SimpleXML extension and errors if missing.
WP_Recovery_Mode::handle_exit_recovery_mode()`wp-includes/class-wp-recovery-mode.php`	Handles a request to exit Recovery Mode.
WP_Recovery_Mode::handle_cookie()`wp-includes/class-wp-recovery-mode.php`	Handles checking for the recovery mode cookie and validating it.
WP_Recovery_Mode_Link_Service::handle_begin_link()`wp-includes/class-wp-recovery-mode-link-service.php`	Enters recovery mode when the user hits wp-login.php with a valid recovery mode link.
WP_Fatal_Error_Handler::display_default_error_template()`wp-includes/class-wp-fatal-error-handler.php`	Displays the default PHP error template.
WP_Customize_Manager::handle_load_themes_request()`wp-includes/class-wp-customize-manager.php`	Loads themes into the theme browsing/installation UI.
wp_load_press_this()`wp-admin/press-this.php`
wp_check_comment_flood()`wp-includes/comment.php`	Checks whether comment flooding is occurring.
wp_ajax_get_post_thumbnail_html()`wp-admin/includes/ajax-actions.php`	Handles retrieving HTML for the featured image via AJAX.
rest_api_loaded()`wp-includes/rest-api.php`	Loads the REST API.
wp_ajax_delete_inactive_widgets()`wp-admin/includes/ajax-actions.php`	Handles removing inactive widgets via AJAX.
WP_Customize_Nav_Menus::ajax_load_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for loading available menu items.
WP_Customize_Nav_Menus::ajax_search_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for searching available menu items.
wp_media_attach_action()`wp-admin/includes/media.php`	Encapsulates the logic for Attach/Detach actions.
File_Upload_Upgrader::__construct()`wp-admin/includes/class-file-upload-upgrader.php`	Construct the upgrader for a form.
WP_Screen::get()`wp-admin/includes/class-wp-screen.php`	Fetches a screen object.
install_theme_information()`wp-admin/includes/theme-install.php`	Displays theme information in dialog box form.
_access_denied_splash()`wp-admin/includes/ms.php`	Displays an access denied message when a user tries to view a site’s dashboard they do not have access to.
check_upload_size()`wp-admin/includes/ms.php`	Determines whether uploaded file exceeds space quota.
WP_Theme_Install_List_Table::prepare_items()`wp-admin/includes/class-wp-theme-install-list-table.php`
install_plugin_information()`wp-admin/includes/plugin-install.php`	Displays plugin information in dialog box form.
wp_check_mysql_version()`wp-admin/includes/upgrade.php`	Checks the version of the installed MySQL binary.
edit_user()`wp-admin/includes/user.php`	Edit user settings based on contents of $_POST
post_preview()`wp-admin/includes/post.php`	Saves a draft or manually autosaves for the purpose of showing a post preview.
write_post()`wp-admin/includes/post.php`	Calls wp_write_post() and handles the errors.
edit_post()`wp-admin/includes/post.php`	Updates an existing post with values provided in `$_POST`.
bulk_edit_posts()`wp-admin/includes/post.php`	Processes the post data for the bulk editing of posts.
wp_ajax_save_widget()`wp-admin/includes/ajax-actions.php`	Handles saving a widget via AJAX.
wp_ajax_upload_attachment()`wp-admin/includes/ajax-actions.php`	Handles uploading attachments via AJAX.
wp_ajax_image_editor()`wp-admin/includes/ajax-actions.php`	Handles image editing via AJAX.
wp_ajax_set_post_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image via AJAX.
wp_ajax_date_format()`wp-admin/includes/ajax-actions.php`	Handles formatting a date via AJAX.
wp_ajax_time_format()`wp-admin/includes/ajax-actions.php`	Handles formatting a time via AJAX.
wp_ajax_wp_remove_post_lock()`wp-admin/includes/ajax-actions.php`	Handles removing a post lock via AJAX.
wp_ajax_dismiss_wp_pointer()`wp-admin/includes/ajax-actions.php`	Handles dismissing a WordPress pointer via AJAX.
wp_ajax_add_menu_item()`wp-admin/includes/ajax-actions.php`	Handles adding a menu item via AJAX.
wp_ajax_add_meta()`wp-admin/includes/ajax-actions.php`	Handles adding meta via AJAX.
wp_ajax_add_user()`wp-admin/includes/ajax-actions.php`	Handles adding a user via AJAX.
wp_ajax_closed_postboxes()`wp-admin/includes/ajax-actions.php`	Handles closed post boxes via AJAX.
wp_ajax_hidden_columns()`wp-admin/includes/ajax-actions.php`	Handles hidden columns via AJAX.
wp_ajax_update_welcome_panel()`wp-admin/includes/ajax-actions.php`	Handles updating whether to display the welcome panel via AJAX.
wp_ajax_menu_get_metabox()`wp-admin/includes/ajax-actions.php`	Handles for retrieving menu meta boxes via AJAX.
wp_ajax_wp_link_ajax()`wp-admin/includes/ajax-actions.php`	Handles internal linking via AJAX.
wp_ajax_menu_locations_save()`wp-admin/includes/ajax-actions.php`	Handles saving menu locations via AJAX.
wp_ajax_meta_box_order()`wp-admin/includes/ajax-actions.php`	Handles saving the meta box order via AJAX.
wp_ajax_menu_quick_search()`wp-admin/includes/ajax-actions.php`	Handles menu quick searching via AJAX.
wp_ajax_get_permalink()`wp-admin/includes/ajax-actions.php`	Handles retrieving a permalink via AJAX.
wp_ajax_sample_permalink()`wp-admin/includes/ajax-actions.php`	Handles retrieving a sample permalink via AJAX.
wp_ajax_inline_save()`wp-admin/includes/ajax-actions.php`	Handles Quick Edit saving a post from a list table via AJAX.
wp_ajax_inline_save_tax()`wp-admin/includes/ajax-actions.php`	Handles Quick Edit saving for a term via AJAX.
wp_ajax_widgets_order()`wp-admin/includes/ajax-actions.php`	Handles saving the widgets order via AJAX.
wp_ajax_dashboard_widgets()`wp-admin/includes/ajax-actions.php`	Handles dashboard widgets via AJAX.
wp_ajax_logged_in()`wp-admin/includes/ajax-actions.php`	Handles Customizer preview logged-in status via AJAX.
_wp_ajax_add_hierarchical_term()`wp-admin/includes/ajax-actions.php`	Handles adding a hierarchical term via AJAX.
wp_ajax_delete_comment()`wp-admin/includes/ajax-actions.php`	Handles deleting a comment via AJAX.
wp_ajax_delete_tag()`wp-admin/includes/ajax-actions.php`	Handles deleting a tag via AJAX.
wp_ajax_delete_link()`wp-admin/includes/ajax-actions.php`	Handles deleting a link via AJAX.
wp_ajax_delete_meta()`wp-admin/includes/ajax-actions.php`	Handles deleting meta via AJAX.
wp_ajax_delete_post()`wp-admin/includes/ajax-actions.php`	Handles deleting a post via AJAX.
wp_ajax_trash_post()`wp-admin/includes/ajax-actions.php`	Handles sending a post to the Trash via AJAX.
wp_ajax_delete_page()`wp-admin/includes/ajax-actions.php`	Handles deleting a page via AJAX.
wp_ajax_dim_comment()`wp-admin/includes/ajax-actions.php`	Handles dimming a comment via AJAX.
wp_ajax_add_link_category()`wp-admin/includes/ajax-actions.php`	Handles adding a link category via AJAX.
wp_ajax_add_tag()`wp-admin/includes/ajax-actions.php`	Handles adding a tag via AJAX.
wp_ajax_get_tagcloud()`wp-admin/includes/ajax-actions.php`	Handles getting a tagcloud via AJAX.
wp_ajax_get_comments()`wp-admin/includes/ajax-actions.php`	Handles getting comments via AJAX.
wp_ajax_replyto_comment()`wp-admin/includes/ajax-actions.php`	Handles replying to a comment via AJAX.
wp_ajax_edit_comment()`wp-admin/includes/ajax-actions.php`	Handles editing a comment via AJAX.
wp_ajax_fetch_list()`wp-admin/includes/ajax-actions.php`	Handles fetching a list table via AJAX.
wp_ajax_ajax_tag_search()`wp-admin/includes/ajax-actions.php`	Handles tag search via AJAX.
wp_ajax_wp_compression_test()`wp-admin/includes/ajax-actions.php`	Handles compression testing via AJAX.
wp_ajax_imgedit_preview()`wp-admin/includes/ajax-actions.php`	Handles image editor previews via AJAX.
wp_ajax_oembed_cache()`wp-admin/includes/ajax-actions.php`	Handles oEmbed caching via AJAX.
wp_ajax_autocomplete_user()`wp-admin/includes/ajax-actions.php`	Handles user autocomplete via AJAX.
wp_link_manager_disabled_message()`wp-admin/includes/bookmark.php`	Outputs the ‘disabled’ message for the WordPress Link Manager.
edit_link()`wp-admin/includes/bookmark.php`	Updates or inserts a link using values provided in $_POST.
wpmu_checkAvailableSpace()`wp-admin/includes/ms-deprecated.php`	Determines if the available space defined by the admin has been exceeded by the user.
WP_Terms_List_Table::__construct()`wp-admin/includes/class-wp-terms-list-table.php`	Constructor.
validate_file_to_edit()`wp-admin/includes/file.php`	Makes sure that the file that was requested to be edited is allowed to be edited.
edit_comment()`wp-admin/includes/comment.php`	Updates a comment with values provided in $_POST.
Custom_Image_Header::step_2()`wp-admin/includes/class-custom-image-header.php`	Displays second step of custom header image page.
Custom_Image_Header::step_2_manage_upload()`wp-admin/includes/class-custom-image-header.php`	Uploads the file to be cropped in the second step.
Custom_Image_Header::step_3()`wp-admin/includes/class-custom-image-header.php`	Displays third step of custom header image page.
Custom_Image_Header::admin_page()`wp-admin/includes/class-custom-image-header.php`	Displays the page based on the current step.
confirm_delete_users()`wp-admin/includes/ms.php`
Custom_Background::handle_upload()`wp-admin/includes/class-custom-background.php`	Handles an Image upload for the background image.
WP_Customize_Manager::wp_die()`wp-includes/class-wp-customize-manager.php`	Custom wp_die wrapper. Returns either the standard message for UI or the Ajax message.
WP_Customize_Manager::setup_theme()`wp-includes/class-wp-customize-manager.php`	Starts preview and customize theme.
switch_theme()`wp-includes/theme.php`	Switches the theme.
wp_redirect()`wp-includes/pluggable.php`	Redirects to another page.
check_ajax_referer()`wp-includes/pluggable.php`	Verifies the Ajax request to prevent processing requests external of the blog.
WP::parse_request()`wp-includes/class-wp.php`	Parses the request to find the correct WordPress query.
wp_check_php_mysql_versions()`wp-includes/load.php`	Checks for the required PHP version, and the mysqli extension or a database drop-in.
wp_maintenance()`wp-includes/load.php`	Dies with a maintenance message when conditions are met.
wp_set_wpdb_vars()`wp-includes/load.php`	Sets the database table prefix and the format specifiers for database table columns.
wp_not_installed()`wp-includes/load.php`	Redirects to the installer if WordPress is not installed.
wp_send_json()`wp-includes/functions.php`	Sends a JSON response back to an Ajax request.
dead_db()`wp-includes/functions.php`	Loads custom DB error or display WordPress DB error.
wp_nonce_ays()`wp-includes/functions.php`	Displays “Are You Sure” message to confirm the action being taken.
do_feed()`wp-includes/functions.php`	Loads the feed template from the use of an action hook.
WP_Ajax_Response::send()`wp-includes/class-wp-ajax-response.php`	Display XML formatted responses.
wp_protect_special_option()`wp-includes/option.php`	Protects WordPress special option from being modified.
_show_post_preview()`wp-includes/revision.php`	Filters the latest content for preview from the post autosave.
maybe_add_existing_user_to_blog()`wp-includes/ms-functions.php`	Adds a new user to a blog by visiting /newbloguser/{key}/.
ms_not_installed()`wp-includes/ms-load.php`	Displays a failure message.
wpmu_admin_do_redirect()`wp-includes/ms-deprecated.php`	Redirect a user based on $_GET or $_POST arguments.
ms_site_check()`wp-includes/ms-load.php`	Checks status of current blog.
wpdb::bail()`wp-includes/class-wpdb.php`	Wraps errors in a nice header and footer and dies.
wpdb::print_error()`wp-includes/class-wpdb.php`	Prints SQL/DB error.
WP_Customize_Widgets::wp_ajax_update_widget()`wp-includes/class-wp-customize-widgets.php`	Updates widget settings asynchronously.
wp_allow_comment()`wp-includes/comment.php`	Validates whether this comment is allowed to be made.

Show 107 more Show less

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.

User Contributed Notes

Codex 10 years ago

Test to see what is in the $post variable in a filter:

/**
 * Add new body class.
 *
 * Testing what is in the $post variable.
 *
 * @param array $classes Body classes.
 */
function wpdocs_add_body_class( $classes ) {
	/** @global WP_Post $post */
	global $post;

	wp_die( '<pre>' . var_export( $post, true ) . '</pre>' );
}
add_filter( 'body_class', 'wpdocs_add_body_class' );

Skip to note 4 content

capbussat 3 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
You can use wp_die() at the end of function to close an AJAX request. You receive HTML code for example and you can use it by JS. But consider using wp_send_json() instead if you need to return a correct string value to an AJAX request. (I assume you can return also arrays or objects). Codex indicates that wp_send_json() uses wp_die().
```
wp_die( 'string' ) // received by JS as '\nstring' 
wp_send_json( 'string' ) // received by JS as 'string'
```
Log in to add feedback

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

In this article