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.

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 | 400 |
| 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 |
| No | Hook names, login state, plugin active |
Handler ran but never answered | 200 |
| Your callback returned without calling | The end of your callback |
Nonce missing or wrong | 403 |
|
| Nonce action string, cached page, user state |
Your own error response | Whatever you pass (default 200) |
| 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. |
|
Text in front of the JSON | 200 |
| Something printed output before | 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 is400and0. - Logged out:
wp_ajax_nopriv_{action}fires. If nothing is attached, same400and0.
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:
- Open the Network tab and tick Preserve log, so a redirect or page reload does not wipe the evidence.
- Filter by Fetch/XHR, then type
admin-ajaxin the filter box. - Trigger the action and click the request row.
- In Headers, read the status and the response
Content-Type. JSON should sayapplication/json. - In Payload, confirm
action, your nonce and every field you expected are really there, with the right values. - 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.
0with400: WordPress found no handler. Check the action string character by character, the login state, and whether the file with youradd_action()call actually loads on AJAX requests.0with200: your handler ran and ended without answering. WordPress falls through to its defaultwp_die( '0' )at the bottom of the file. Addwp_send_json_success(),wp_send_json_error()orwp_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 falseA 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 |
|---|---|
| 200, handler ran |
| 200, handler ran |
JSON body with | 400 and |
JSON body, with | 403 and |
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 responsesTrigger 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:14Turn 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 | 401, |
Bad or missing nonce | 403 and | 403, |
JSON request body | Not in | Read natively from the request object |
Permission check | Your code, easy to forget |
|
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.
- Did a request leave the browser? No request means a JavaScript problem. Read the Console.
- Did it reach WordPress? An HTML body from a firewall or a host error page means no. Check server logs.
- Does the Payload hold what you think? Check
action, the nonce field name and every value. Confirm the content type is form-encoded. - Read the status and body together. Use the table at the top.
400and0: hook.403and-1: nonce.500: log.200and0: missing response. - Turn on
WP_DEBUG_LOGand repeat. Add oneerror_log()at the top of the callback to prove it runs. - Check login state. Repeat the call as a guest and as a logged-in user. Different results point at
noprivor a cached nonce. - Add Query Monitor and read the
X-QM-php_errorsheaders for errors the handler swallowed. - Check the layer above WordPress. Security plugins, firewalls and CDNs can block
admin-ajax.phpfor 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
400until a moderator had the poster build the URL withadmin_url()and pass it withwp_localize_script(), plus a nonce. - A handler that works for one login state. A chat plugin thread from about September 2020 showed
400for 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.phpswitched a plugin to a REST endpoint and still got400from 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
actionor 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
actionfield 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()orwp_die(). - No
echoorprint_rleft 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_LOGon.
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.
Plugins we build and run
We maintain these ourselves, which is why we can support them on your site.
- BuddyNextThe self-hosted community engine for WordPress
- BuddyXFree community theme, Pro when you outgrow it
- ReignPremium community theme. Add pieces, build anything
- JetonomyCommunity forum and Q&A for WordPress
- EventonomyEvents and RSVPs for WordPress communities
- LearnomyCourses and learning communities on WordPress
- ListoraDirectories and listings your members can browse
- SnipShareCode sharing built for developer communities
- WB Ad ManagerAd placements that turn traffic into revenue
- WP Career BoardA job board your community actually uses
- WP Sell ServicesSell services with offers, orders, and payouts
- MediaVersePhotos, video, and media albums for members
- WB GamificationPoints, badges, and rewards that keep members active
- Product RoadmapPublic roadmaps with voting your users trust



