WordPress Debug Guide: Finding and Fixing Silent Plugin Failures

👁 5 views

Yesterday I deployed a WordPress plugin that looked perfect. Clean code. Proper hooks. Followed the official documentation. It installed without errors, appeared in the admin panel, and seemed to work.

It was completely broken.

The plugin registered four new “abilities” for AI agents to use — things like generating featured images and excerpts. Every single one failed silently. No PHP errors. No warnings. Just… nothing happened when an AI agent tried to use them.

Here’s how I found and fixed the bug, and what it taught me about WordPress debug practices that every plugin developer should know.

The Context: Building WordPress Abilities for AI Agents

WordPress 6.9 introduced something called the Abilities API — a standardized way for plugins to expose functionality that AI agents (like OpenClaw or Claude) can discover and use. Think of it like the REST API, but designed specifically for AI-to-WordPress communication.

The plugin I built, mcp-media-generator, was supposed to let AI agents:

• Generate post excerpts using Gemini
• Create featured images using Imagen
• Batch process multiple posts at once
• Check generation status

Four abilities. Four failures. Zero visible errors.

The Symptom: “Ability Does Not Exist”

When an AI agent tried to call any of these abilities, the WordPress debug log showed:

Ability category 'mcp-media' is not registered
Ability 'mcp-media/generate-excerpt' does not exist

The first clue. WordPress couldn’t find the abilities I thought I’d registered. But the registration code was there — I could see it in the file. What was wrong?

WordPress Debug Step 1: Enable WP_DEBUG_LOG

If you’re not already logging errors to a file, you’re debugging blind. Add this to your wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

The WP_DEBUG_DISPLAY setting is crucial on production sites — it writes errors to /wp-content/debug.log instead of showing them to visitors. Check that file regularly:

tail -f wp-content/debug.log

This is where I found the “category not registered” errors. Without the log, I would have been completely stuck.

The Bug: Wrong Hook, Wrong Order

Here’s what I had written:

// ❌ WRONG - This doesn't work
add_filter( 'mcp_adapter_default_server_config', function( $config ) {
    $config['tools'][] = [
        'name' => 'mcp-media/generate-excerpt',
        // ... tool definition
    ];
    return $config;
});

I was trying to add abilities directly to the MCP adapter’s config filter. It seemed logical — that’s where the tools list lives, right?

Wrong. The Abilities API requires a two-step registration process:

// ✅ CORRECT - Register category FIRST
add_action( 'wp_abilities_api_categories_init', function() {
    wp_register_ability_category( 'mcp-media', [
        'label'       => 'MCP Media Generation',
        'description' => 'AI-powered media generation abilities',
    ]);
});

// ✅ THEN register individual abilities
add_action( 'wp_abilities_api_init', function() {
    register_ability( 'mcp-media/generate-excerpt', [
        'label'       => 'Generate Excerpt',
        'description' => 'Generate a post excerpt using AI',
        'callback'    => 'mcp_generate_excerpt_handler',
        'input_schema' => [
            'type' => 'object',
            'properties' => [
                'post_id' => [ 'type' => 'integer', 'required' => true ],
            ],
        ],
    ]);
});

The WordPress API hooks fire in a specific order. wp_abilities_api_categories_init runs before wp_abilities_api_init. If you try to register an ability before its category exists, WordPress silently ignores it.

Why Silent Failures Are the Worst

This bug was particularly nasty because:

1. No PHP errors or warnings were thrown
2. The plugin activated successfully
3. The admin UI showed everything was fine
4. Only the actual functionality was broken

WordPress’s hook system is powerful but unforgiving. If you hook into the wrong action, or hook at the wrong priority, things just… don’t happen. No exceptions. No “hey, you registered this ability wrong” message. Silence.

WordPress Debug Step 2: Read Existing Code First

The fix was obvious once I looked at how another plugin on the same site handled ability registration. The master-control-press theme had working abilities — I could have just copied that pattern.

Lesson learned: Before writing new WordPress code, check if something similar already exists in your codebase. Reading working code beats guessing at APIs every time.

The Fix: Two Hooks, Correct Order

Here’s the complete working pattern for registering WordPress abilities:

<?php
/**
 * Register ability category on the correct hook
 */
add_action( 'wp_abilities_api_categories_init', function() {
    wp_register_ability_category( 'my-plugin', [
        'label'       => __( 'My Plugin Abilities', 'my-plugin' ),
        'description' => __( 'Custom abilities for AI agents', 'my-plugin' ),
    ]);
}, 10 );

/**
 * Register individual abilities AFTER category exists
 */
add_action( 'wp_abilities_api_init', function() {
    // The category must exist before we can add abilities to it
    register_ability( 'my-plugin/do-something', [
        'label'        => __( 'Do Something', 'my-plugin' ),
        'description'  => __( 'Description of what this does', 'my-plugin' ),
        'callback'     => 'my_plugin_do_something_handler',
        'input_schema' => [
            'type'       => 'object',
            'properties' => [
                'param' => [
                    'type'     => 'string',
                    'required' => true,
                ],
            ],
        ],
    ]);
}, 10 );

Key points:

• wp_abilities_api_categories_init runs first — register your category here
• wp_abilities_api_init runs second — register individual abilities here
• Always include an input_schema — AI agents need to know what parameters to send
• Test by calling the ability after deployment, not just checking if the plugin activates

What This Means for AI + WordPress Development

We’re in the early days of AI agents working with WordPress. The Abilities API is new. The patterns aren’t well-documented yet. You’re going to hit bugs like this.

The debug workflow that saved me:

1. Enable WP_DEBUG_LOG — You need to see errors to fix them
2. Check the debug log after every deployment — Don’t assume “no visible errors” means “working”
3. Read existing working code — Copy patterns from plugins that already work
4. Test the actual functionality — Not just installation, but real usage
5. Document what you learn — The next developer (or AI agent) will thank you

Building tools for AI agents to use means thinking about failure modes differently. The AI can’t see your screen. It can’t interpret vague error messages. It needs things to either work or fail with clear, machine-readable feedback.

Silent failures are the enemy.

Try It Yourself

If you’re building WordPress plugins that expose abilities to AI agents, start with the pattern above. Register your category first, then your abilities. Always include input schemas. And for the love of all that is holy, check your debug log after deployment.

The WordPress Abilities API is going to be huge for anyone building AI-powered WordPress tools. Get the fundamentals right now, and you’ll be ahead of the curve when everyone else discovers this space.

Building something with WordPress and AI? We’re documenting the journey at Master Control Press. Subscribe for updates on the tools and techniques that are actually working.