Debugging & Profiling

How to Debug WordPress AJAX Requests (admin-ajax.php Troubleshooting)

Read the status code and body from admin-ajax.php together: 400 with 0, 403 with -1 or a 500 each point to a different fix. Tested on WordPress 7.1.4.

Varun DubeyVarun Dubey
·14 min read
Browser Network tab listing four admin-ajax.php requests with status 400, 403, 500 and 200

To debug a WordPress AJAX request, open the browser Network tab, find the call to admin-ajax.php and read two things: the HTTP status and the first few characters of the response body. Those two facts tell you which layer failed. A 400 with the body 0 means no handler is registered for that action, a 403 with -1 means the nonce check failed, a 500 means PHP crashed, and valid JSON with "success":false means your own handler ran and said no.

We tested every status and body in this guide on 16 Nov 2026 against WordPress 7.1.4 on PHP 8.3 with Apache, using a small test plugin and Query Monitor 4.1.1. Where an older tutorial (including an earlier version of this post) says something different, we trust the core source and the test. One example: unmatched actions return HTTP 400 now, not 200.

What do the status code and body from admin-ajax.php mean?

Start here. The table lists what we actually got back from a stock WordPress 7.1.4 install for each failure. The body is the part most guides skip, and it is the quickest way to tell a missing handler from a failed nonce.

What you see

HTTP status

Body

What it means

Where to look next

No action sent, or an empty one

400

0

The request never named a handler. Often a JSON body or a typo in the field name.

Payload tab, request content type

Action not registered for this user state

400

0

No wp_ajax_* or wp_ajax_nopriv_* hook matches. Logged-in users never fall through to the nopriv hook.

Hook names, login state, plugin active

Handler ran but never answered

200

0

Your callback returned without calling wp_send_json* or wp_die().

The end of your callback

Nonce missing or wrong

403

-1

check_ajax_referer() failed and stopped the request.

Nonce action string, cached page, user state

Your own error response

Whatever you pass (default 200)

{"success":false,...}

Handler ran and refused. The status is yours to choose.

Your validation and capability checks

PHP fatal error

500

The critical-error page (HTML)

A fatal error stopped the request before a response.

debug.log, Query Monitor

Text in front of the JSON

200

stray {"success":true,...}

Something printed output before wp_send_json(). The content type also flips to text/html.

Your handler and plugin files for stray echo or whitespace

A web page, not JSON

403 or 5xx

HTML from a firewall or host

The request did not reach WordPress.

Server and firewall logs

Checked on 16 Nov 2026. The first two rows come straight from wp-admin/admin-ajax.php in WordPress 7.1.4, which calls wp_die( '0', 400 ) in both cases. The rest we reproduced with curl.

How does admin-ajax.php pick the code that runs?

Every WordPress AJAX call goes to one file, wp-admin/admin-ajax.php. It defines DOING_AJAX, loads WordPress with all active plugins, and reads the action value from $_REQUEST. Then it fires one of two hooks, depending on whether the visitor is logged in.

  • Logged in: wp_ajax_{action} fires. If nothing is attached, the response is 400 and 0.
  • Logged out: wp_ajax_nopriv_{action} fires. If nothing is attached, same 400 and 0.

The two hooks never cross over. We registered one action for logged-in users only and another for guests only, then called each from each state. The guests-only action returned 400 and 0 to a logged-in admin. This catches people who test as admin, ship, and find that visitors get a failure, or the reverse. The official AJAX chapter of the Plugin Handbook covers the basic flow, and the reference pages for wp_ajax_{action} and wp_ajax_nopriv_{action} list the hook details.

The request is not a page load, so no theme template renders. Your plugin code does load, and so does every other active plugin. That matters later, when we look at why one slow plugin makes every AJAX call slow.

How do I read an AJAX request in browser DevTools?

Open DevTools before you trigger the request, because the Network tab only records traffic from the moment it is open. Use F12, or Cmd+Option+I on a Mac. Then:

  1. Open the Network tab and tick Preserve log, so a redirect or page reload does not wipe the evidence.
  2. Filter by Fetch/XHR, then type admin-ajax in the filter box.
  3. Trigger the action and click the request row.
  4. In Headers, read the status and the response Content-Type. JSON should say application/json.
  5. In Payload, confirm action, your nonce and every field you expected are really there, with the right values.
  6. In Response, read the raw text. Compare it to the table above.

If no request appears at all, the problem is in the browser and not on the server. Check the Console tab for a JavaScript error that stopped your script before it sent anything, and confirm the script is actually loaded on that page.

Page caches and CDNs can change what you see. A response served from cache shows a 304 or a cache header and never reaches PHP, so no log line appears on the server. Tick Disable cache while DevTools is open when you are debugging. Our guide to the cookies that bypass a WordPress page cache explains why logged-in traffic behaves differently from guest traffic.

Why does admin-ajax.php return 0, and which 0 is it?

The answer depends on the status code next to it. Two different situations print the same character.

  • 0 with 400: WordPress found no handler. Check the action string character by character, the login state, and whether the file with your add_action() call actually loads on AJAX requests.
  • 0 with 200: your handler ran and ended without answering. WordPress falls through to its default wp_die( '0' ) at the bottom of the file. Add wp_send_json_success(), wp_send_json_error() or wp_die() to every path in the callback.

Older tutorials, including the first version of this post, say a missing handler returns 0 with HTTP 200. The current core file returns 400, so a fetch wrapper that throws on non-2xx statuses will now raise an error for a missing handler.

To tell whether your handler is reached at all, put a log line at the top of the callback and watch wp-content/debug.log. If nothing appears, the hook is not attached for this request. Turn on logging as shown in the wp-config.php section below. If the log file is never created, our guide to why debug.log stays empty covers the usual causes.

Register the hook where it always loads: at the top level of the plugin file, or inside init. Registering inside a function that only runs while rendering a front-end template means the hook does not exist on admin-ajax.php, because that request never renders a template.

Why do I get a 403 and -1 on an AJAX request?

A 403 with -1 is the signature of a failed check_ajax_referer(). The function reads the nonce from the field you name, then from _ajax_nonce, then from _wpnonce, runs wp_verify_nonce(), and if the answer is false it ends the request with wp_die( -1, 403 ). So the usual causes are all about the nonce reaching PHP.

Is the field name right?

If your handler calls check_ajax_referer( 'demo_nonce', 'nonce' ), the request must send a field called nonce. Sending it as security or _nonce gives a 403 every time. Look at the Payload tab and compare names.

Do the action strings match?

The string passed to wp_create_nonce() must equal the string passed to check_ajax_referer(). save_item and save-item are different nonces. Keep the string in one constant or one shared function.

Was the nonce made for a different user?

A nonce is tied to the action, the user ID and the login session. We asked for a nonce as a guest and as an admin, then used the guest nonce on the admin session. The result was 403 and -1. The reverse also fails. This is exactly what happens when a full-page cache stores a page that was built for one visitor and serves it to another. The cached page carries a frozen nonce, and the person it is shown to is somebody else.

Fixes that work: exclude the page from the cache, fetch the nonce with a separate uncached AJAX call after load, or read it from a logged-in-only fragment. Do not hardcode a nonce into a JavaScript file, and do not print it into a page you let the CDN cache.

Has it expired?

By default a nonce is valid for between 12 and 24 hours, because WordPress works in two 12-hour ticks. The nonce_life filter changes the lifespan. A tab left open overnight will fail on the next click. wp_verify_nonce() returns 1 for a nonce under 12 hours old, 2 for one between 12 and 24 hours, and false after that, so logging the return value shows how close to expiry the user was. The Plugin Handbook adds a useful caveat: nonces are not true one-time tokens, so a nonce proves the request came from your page, and it is not an authorisation check.

// Checked on 16 Nov 2026, WordPress 7.1.4
// Temporary: see exactly what the nonce check returned.
$result = wp_verify_nonce( isset( $_POST['nonce'] ) ? $_POST['nonce'] : '', 'demo_nonce' );
error_log( 'demo_nonce check: ' . var_export( $result, true ) ); // 1, 2 or false

A nonce check does not replace a capability check. Anyone who can load your page gets a valid nonce. If the action changes data, call current_user_can() inside the handler and answer with wp_send_json_error( ..., 403 ) when it fails.

Why is $_POST empty when I send a JSON body?

Because PHP only fills $_POST for form content types. We sent the same fields three ways against a working handler:

How the request was sent

Result

FormData body

200, handler ran

URLSearchParams body

200, handler ran

JSON body with Content-Type: application/json

400 and 0, because action never arrived

JSON body, with ?action=demo_ok in the URL

403 and -1, because the handler ran but the nonce never arrived

The last row is the confusing one. The action in the query string is enough to reach the handler, so the symptom changes from 0 to -1 and people start chasing the nonce. The nonce is fine. The body is simply not in $_POST. Send form-encoded data, or move to a REST route, which reads JSON natively.

Why is my AJAX response broken or not valid JSON?

Anything printed before wp_send_json() lands in front of the JSON, and the headers are already sent as text/html. We added a single echo "stray " to a handler and the browser received stray {"success":true,"data":"x"} with a text/html content type. Both response.json() and jQuery with dataType: 'json' then fail.

The usual sources of stray output are an echo or print_r left in a handler, whitespace or a byte-order mark before <?php in a plugin file, and a plugin that prints a notice itself.

One cause that older guides blame is no longer true on a stock install. WordPress forces display_errors off for AJAX requests inside wp_debug_mode(), whatever WP_DEBUG_DISPLAY says. We triggered an undefined-variable warning inside an AJAX handler with debug on and got clean JSON, with the warning in debug.log only. If you do see PHP notices in an AJAX response, something overrode display_errors after WordPress set it, or the error fired before WordPress loaded, for example in wp-config.php.

How do I turn on logging and find the error behind a 500?

A 500 from admin-ajax.php is a PHP fatal error or an uncaught exception. WordPress catches it and returns the critical-error page, which tells you nothing. The detail goes to the log. Add this to wp-config.php above the line that says to stop editing:

// Checked on 16 Nov 2026, WordPress 7.1.4
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );      // writes wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // keep errors out of pages and responses

Trigger the request again and open wp-content/debug.log. Our deliberate call to an undefined function produced this, with a full stack trace that ended at the do_action( 'wp_ajax_demo_fatal' ) line in admin-ajax.php:

PHP Fatal error:  Uncaught Error: Call to undefined function nonexistent_function()
in /var/www/html/wp-content/mu-plugins/t.php:14

Turn debug off again when you finish, and delete the log if it holds anything sensitive. The official debugging guide documents each constant.

How do I pass the AJAX URL and nonce to JavaScript on the front end?

In the admin, WordPress prints a global ajaxurl variable for you. On public pages it does not, so you must pass the URL yourself. The Plugin Handbook says so directly. The standard tool is wp_localize_script(), called after the script is registered or enqueued, with the same handle:

// Checked on 16 Nov 2026, WordPress 7.1.4
add_action( 'wp_enqueue_scripts', function () {
	wp_enqueue_script( 'demo-ajax', plugins_url( 'demo-ajax.js', __FILE__ ), array(), '1.0', true );
	wp_localize_script( 'demo-ajax', 'demoAjax', array(
		'url'   => admin_url( 'admin-ajax.php' ),
		'nonce' => wp_create_nonce( 'demo_nonce' ),
	) );
} );

On a test page this printed var demoAjax = {"url":"http://localhost:8951/wp-admin/admin-ajax.php","nonce":"..."}; just before the script tag. If demoAjax is undefined in the console, the handle does not match, the script did not load on that page, or wp_localize_script() ran before the script was registered. The function returns false in that last case. wp_add_inline_script() (available since WordPress 4.5) is the alternative when you want to print JSON yourself. See the reference for wp_localize_script() and wp_add_inline_script().

A relative or hardcoded URL is a classic cause of a 400 on sites with a different home and site URL or a subdirectory install. A moderator in a wordpress.org thread fixed one by building the URL with admin_url() in PHP and passing it through wp_localize_script(), as we describe in the problems box below.

What does a correct handler and request look like?

This pair is the one we used for every test above. The handler checks the nonce, checks capability when it needs to, validates input, and always answers through wp_send_json_*.

// Checked on 16 Nov 2026, WordPress 7.1.4, PHP 8.3
add_action( 'wp_ajax_demo_ok', 'demo_ok' );
add_action( 'wp_ajax_nopriv_demo_ok', 'demo_ok' ); // only if guests may call it

function demo_ok() {
	check_ajax_referer( 'demo_nonce', 'nonce' );    // 403 and -1 on failure

	$id = isset( $_POST['id'] ) ? absint( $_POST['id'] ) : 0;
	if ( ! $id ) {
		wp_send_json_error( array( 'message' => 'Missing id' ), 400 );
	}

	wp_send_json_success( array( 'id' => $id ) );   // ends the request
}
// Checked on 16 Nov 2026
async function demoCall( id ) {
  const body = new URLSearchParams( { action: 'demo_ok', nonce: demoAjax.nonce, id } );
  const res = await fetch( demoAjax.url, { method: 'POST', body } );
  const text = await res.text();
  let json;
  try { json = JSON.parse( text ); } catch ( e ) {
    console.error( 'Not JSON. Status', res.status, 'Body starts:', text.slice( 0, 80 ) );
    return null;
  }
  if ( ! json.success ) { console.warn( 'Handler said no', res.status, json.data ); return null; }
  return json.data;
}

Reading the body as text first, then parsing, is a debugging habit worth keeping. When it fails, the console line shows the status and the first 80 characters, which is all the table at the top needs. Status codes are not uniform: both wp_send_json_error() and wp_send_json() accept an HTTP status as an optional argument, and without it the status is 200 even for "success":false. So check json.success, and use the status argument when you want fetch wrappers to see an error. The reference page for wp_send_json_error() shows that a WP_Error is converted to a list of code and message pairs, which we confirmed: {"success":false,"data":[{"code":"bad","message":"Nope"}]}.

Also avoid redirects inside AJAX handlers. A handler that called wp_safe_redirect() and exited returned a bare 302 with an empty body. The browser follows it as a fetch and receives the home page HTML, which then fails to parse.

Can Query Monitor help debug an AJAX request?

Yes, and it is the fastest way to see a PHP error that your handler hid. For a logged-in user with permission, Query Monitor adds X-QM-* headers to admin-ajax.php responses. With Query Monitor 4.1.1 installed, our warning test returned these headers on a response whose body was valid JSON:

X-QM-overview-time-taken: 0.0453
X-QM-overview-memory: 3.7 MB
X-QM-php_errors-count: 1
X-QM-php_errors-error-1: {"level":"warning","message":"Undefined variable $undefined_var","file":"wp-content/mu-plugins/t.php","line":12, ...}

Open the request in the Network tab and look at the response headers. A count above zero means PHP raised errors during the call, and the JSON in the header gives the file, line and call stack. The same headers appear on REST responses. Our full walk through the panels is in the Query Monitor developer tutorial.

Should I use the REST API instead of admin-ajax.php?

For new code, usually yes. The REST API gives you routes, JSON input, a mandatory permission callback and normal HTTP status codes. For code that already works on admin-ajax.php, there is no need to rewrite it. Both are supported. Cookie-authenticated REST requests need the X-WP-Nonce header, and the failure codes are different from AJAX:

Situation

admin-ajax.php

REST route (cookie auth)

Not logged in, action needs login

400 and 0 (no handler for guests)

401, rest_not_logged_in

Bad or missing nonce

403 and -1

403, rest_cookie_invalid_nonce

JSON request body

Not in $_POST

Read natively from the request object

Permission check

Your code, easy to forget

permission_callback is required for a route

Who can call it

Anyone who can reach the file and name an action

Anyone, filtered by the callback

We confirmed the REST codes by calling /wp/v2/users/me three ways: without a nonce (401), with a wrong nonce (403), and with the nonce from wpApiSettings (200). The REST authentication guide explains the header. Switching does not change one thing: a nonce proves origin, and your permission callback decides who may act.

Why does admin-ajax.php slow down or overload my server?

Because each request boots all of WordPress and every active plugin, and some requests repeat on a timer. The biggest repeating source is the Heartbeat API, which sends action=heartbeat to admin-ajax.php. In the core file heartbeat.js the default main interval is 60 seconds, and the Plugin Handbook describes a range of 15 to 120 seconds. Several editors with several tabs each add up fast. Hosting providers such as Pressable call it often the largest source of admin-ajax.php traffic on a site.

To find the culprit, filter the Network tab (or your access log) by admin-ajax and read the action value. A steady rhythm of heartbeat calls is Heartbeat. Irregular calls with a plugin-specific action name are that plugin. Our guide to controlling the Heartbeat API shows how to slow it down without breaking autosave, and our look at time to first byte covers the server-side costs every AJAX call also pays.

What is a repeatable workflow for debugging AJAX?

Work from the network inward. Each step answers one question, and you stop at the first step that fails.

  1. Did a request leave the browser? No request means a JavaScript problem. Read the Console.
  2. Did it reach WordPress? An HTML body from a firewall or a host error page means no. Check server logs.
  3. Does the Payload hold what you think? Check action, the nonce field name and every value. Confirm the content type is form-encoded.
  4. Read the status and body together. Use the table at the top. 400 and 0: hook. 403 and -1: nonce. 500: log. 200 and 0: missing response.
  5. Turn on WP_DEBUG_LOG and repeat. Add one error_log() at the top of the callback to prove it runs.
  6. Check login state. Repeat the call as a guest and as a logged-in user. Different results point at nopriv or a cached nonce.
  7. Add Query Monitor and read the X-QM-php_errors headers for errors the handler swallowed.
  8. Check the layer above WordPress. Security plugins, firewalls and CDNs can block admin-ajax.php for logged-out users. Switch each off in turn on a staging copy.

What common mistakes do people report with admin-ajax.php?

We read wordpress.org support threads and the vendor guides we cite above on 16 Nov 2026. These are the problems that come up repeatedly. Each link goes to the original thread.

  • A relative or computed URL. In a support thread from around 2021 to 2022, a jQuery call got 400 until a moderator had the poster build the URL with admin_url() and pass it with wp_localize_script(), plus a nonce.
  • A handler that works for one login state. A chat plugin thread from about September 2020 showed 400 for logged-in users only. Guests worked. The plugin author fixed it in a release. The same shape appears whenever only one of the two hooks is registered.
  • Rerouting around the block. In a 2018 thread a site owner whose host blocked admin-ajax.php switched a plugin to a REST endpoint and still got 400 from a form plugin. The thread has no replies. A workaround for the endpoint does not fix a bad request body.
  • Blaming the server before the request. The WPBeginner guide to the 400 error starts with theme and plugin conflicts, but a missing action or an unregistered handler gives the same status, so read the body before you disable anything.
  • Treating Heartbeat load as a plugin bug. The Pressable article says requests at a steady interval suggest Heartbeat and irregular ones suggest a plugin. Check the action field first.

Checked on 16 Nov 2026. Threads on wordpress.org can be closed or resolved later, so treat the outcomes above as what was visible on that day.

What should I check before I ship an AJAX feature?

  • The same action string in JavaScript, in both add_action() calls and in the nonce.
  • Both hooks registered if guests use it, and only wp_ajax_ if they must not.
  • A capability check inside any handler that writes data.
  • Every code path ends in wp_send_json_success(), wp_send_json_error() or wp_die().
  • No echo or print_r left in the handler.
  • The URL and nonce come from wp_localize_script(), and the page holding the nonce is not cached across users.
  • The request body is form-encoded, or the feature uses a REST route.
  • Tested as a guest, as a subscriber and as an administrator, with WP_DEBUG_LOG on.

Questions people ask

Why does admin-ajax.php return 400?

The request had no usable action, or no handler is attached for that action in the visitor’s login state. Both cases return 400 and 0 on current WordPress. Check the Payload tab, the spelling of the action, and which of the two hooks you registered.

Why does admin-ajax.php return 403 or -1?

The nonce check failed. Confirm the field name, that the nonce was created for the same action string and the same user, and that a cached page did not freeze an old nonce. A 403 with an HTML body means a firewall or security plugin blocked the request, not WordPress.

Is admin-ajax.php deprecated?

Not in the WordPress 7.1.4 core we tested. It still handles core features and plugins, and the Plugin Handbook still documents it. The REST API is the more modern choice for new endpoints, but nothing forces a rewrite.

Do I need wp_ajax_nopriv for logged-in users?

No. Logged-in users only fire wp_ajax_{action}. Register the nopriv hook only when a guest may call the action, and keep in mind that it exposes the handler to anyone on the internet.

Can I send JSON to admin-ajax.php?

Not through $_POST. PHP only fills it for form content types, so a JSON body leaves action and your nonce empty. Send FormData or URLSearchParams, or use a REST route.

How do I find which plugin makes admin-ajax.php slow?

Filter the Network tab or the access log for admin-ajax, read the action value of each call, and match it to a plugin by searching the plugin files for that string. Query Monitor’s overview and queries panels on the same request show where the time goes.

Part of the Wbcom Designs family

The all-in-one WordPress community stack

Also ours: wbcomdesigns.comvapvarun.combrndle.com