> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling errors and failures in Maxi AI Core abilities

> When an ability returns success: false, read the error field and act on it. This page covers every common error code and the correct response to each.

When an ability returns `"success": false`, the `error` field contains a description of what went wrong. The correct response is always to read that field, understand the cause, and fix the conditions or input before retrying. Retrying blindly — without reading the error — will reproduce the same failure.

All server-side errors are also logged to the PHP error log with the prefix `[Maxi AI]`. If you need to debug a call that isn't reaching the server or is producing an unexpected response shape, check your PHP error logs first.

## Common error codes

<AccordionGroup>
  <Accordion title="license_required">
    No valid Maxi AI license is active on this site.

    **What to do:** Purchase a license at [maxicore.ai](https://maxicore.ai), then activate it either through **Settings → Maxi AI License** in your WordPress admin or by calling `maxi/activate-license` with your license key.

    Without an active license, only `maxi/bootstrap-session` and `maxi/activate-license` are callable.
  </Accordion>

  <Accordion title="plan_insufficient">
    Your license is valid, but your current plan does not include the feature group this ability requires.

    **What to do:** The error response includes `required_group` (the group you need) and `plan` (your current plan). Upgrade to Pro at [maxicore.ai](https://maxicore.ai). After upgrading, your new plan takes effect on the next license refresh — up to 12 hours, or immediately by navigating to **Settings → Maxi AI License** and refreshing manually.
  </Accordion>

  <Accordion title="rules_not_acknowledged">
    The ability has a `reject_first` rule that has not been acknowledged in this session. The first call to a write or mutation ability always triggers this — it is not a failure of your input.

    **What to do:** The rule body is attached to this rejection under `_meta._rule`. Read the rule content, then retry the exact same call. The retry is treated as the acknowledgement and the ability runs.

    If your MCP client does not surface the `_meta._rule` body from the rejection (see the Codex quirk below), call `maxi/get-ability-rule` with the `ability_id` first. That call marks the session as acknowledged and your next real call passes through.
  </Accordion>

  <Accordion title="rules_not_installed">
    No rule exists for this ability — the baseline rule set has not been installed on this site yet.

    **What to do:** Call `maxi/rules-sync`. This installs the baseline rules shipped with the plugin. After `rules-sync` completes, retry the original ability call.
  </Accordion>

  <Accordion title="invalid_block_markup">
    The `content` field you sent was empty or whitespace-only. WordPress core's `parse_blocks()` rejected it.

    **What to do:** Provide a non-empty `content` value. You can use Gutenberg block HTML, plain HTML, shortcodes, or classic-editor content. See [Content format](#content-format) below for valid examples.
  </Accordion>

  <Accordion title="invalid_transition">
    You tried to move a note to a status that is not reachable from its current status. Status transitions for notes are PHP-enforced.

    **What to do:** Check the error response for the list of valid target statuses from the note's current state. For example, an `agent-note` at `open` can move to `acknowledged` or `archived` — not directly to `resolved`. The `archived` status is terminal and has no outbound transitions.
  </Accordion>
</AccordionGroup>

## Capability errors

If you receive a permission error when calling an ability, the authenticated WordPress user does not have the WordPress capability that ability requires. This is enforced at execution time on a per-object basis — it is not enough to have `edit_posts` generically; you must also have permission on the specific post being edited.

To fix this, adjust the WordPress user's role or capabilities so they match what the ability needs. For a full breakdown of which capability each ability requires and how to scope agent users correctly, see [User scoping](/security/user-scoping).

## Client quirk: generic error messages

Some MCP clients — Codex is the most common example — collapse any `"success": false` response into the single string `"An error occurred while executing the tool."` This hides the structured `error` field and the `_meta._rule` body that the server sent. The server response is always structured and informative; the client is discarding it.

If you see this generic message, the cause is almost always one of two things:

<Steps>
  <Step title="Check parameter names">
    The ability call used a parameter name that does not match the ability's `input_schema`. WordPress's REST validator emits PHP warnings when it encounters unexpected parameters, which can corrupt the response body before the client parses it.

    Common mistakes: `maxi/get-note`, `maxi/update-note`, and `maxi/delete-note` all use `id` — not `note_id`. `maxi/get-ability-rule` uses `ability_id` — not `ability_name`. `maxi/get-attachment` and `maxi/delete-attachment` use `attachment_id`.

    Retry the call with the exact parameter names from the ability's `input_schema`.
  </Step>

  <Step title="Prefetch the rule for write abilities">
    If parameter names were correct and you are calling a write or mutation ability, the `reject_first` gate triggered a structured rejection that your client is rendering as a generic error.

    Call `maxi/get-ability-rule` with the ability's ID first. This is always callable — it is never itself gated. It marks the session as acknowledged, so your next real call passes through without a rejection.

    ```json theme={null}
    maxi/get-ability-rule { "ability_id": "maxi/create-content" }
    ```
  </Step>

  <Step title="Inspect the audit log">
    If both steps above fail, check whether your retries are reaching the server at all. Call `maxi/get-audit-events` with `category: "rules"` to see rule-gate events logged on the server side.
  </Step>
</Steps>

<Note>
  On MCP clients that render structured errors correctly — Claude Desktop, Cursor, and others — you do not need to prefetch rules for read abilities. Only prefetch `maxi/get-ability-rule` for write abilities (`create-*`, `update-*`, `delete-*`, `bulk-*`, and similar) when using Codex or a client with the same limitation.
</Note>

## Content format

The `content` field accepted by content abilities must pass through WordPress core's `parse_blocks()`. Gutenberg block HTML, plain HTML, shortcodes, and classic-editor content are all valid. The only thing that fails is an empty or whitespace-only string.

For new content, use Gutenberg block format:

```html theme={null}
<!-- wp:paragraph -->
<p>Your text here.</p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>Section Title</h2>
<!-- /wp:heading -->

<!-- wp:heading {"level":3} -->
<h3>Sub-heading</h3>
<!-- /wp:heading -->
```

<Tip>
  Plain HTML and shortcodes also work if you are migrating legacy content. Gutenberg block format is preferred for new content because it produces structured, editable blocks in the WordPress editor.
</Tip>

## Debugging checklist

If an ability is failing and the error message is not clear, work through these steps in order:

1. Read `error` in the response — it always describes the cause.
2. Check your PHP error logs for a line prefixed with `[Maxi AI]`.
3. Confirm the authenticated user has the required WordPress capability for that ability.
4. Confirm your site has an active license with the correct plan for the ability's feature group.
5. For write abilities on Codex: call `maxi/get-ability-rule` first, then retry.
6. For parameter errors: compare the parameter names you sent against the ability's `input_schema`.