Troubleshooting & FAQ
Something not working as expected? Most issues come down to one of a few things — permissions, a missing plugin, a provider key, or licensing. This page lists the common symptoms with their cause and fix, plus answers to questions operators often ask.
Permission & connection issues
The agent says it can’t edit, create, or delete content
Why: Changing content requires an administrator. Maxi enforces this in code — an agent connected as a non-administrator can read everything and write notes, but cannot create, edit, delete, duplicate, schedule, or re-status content. It’s a deliberate safeguard, not a bug.
Fix: Connect the agent as a user with the Administrator role. Check which user it’s connected as by asking “who am I connected as?” If you intend the agent to be read-only, this is working as designed. See Manage Agent Users.
The agent can’t connect — the consent screen rejects my account
Why: Connecting an AI client through the browser sign-in flow requires the account to meet a minimum WordPress capability, set under Settings → AI Connections. By default that’s Administrator, so lower roles (and especially Subscriber) are turned away at the consent screen.
Fix: Sign in with an account that meets the required capability, or lower the required capability in Settings → AI Connections if you intend lower-privileged agents to connect. See Manage Agent Users for how the connection bar and per-action permissions interact.
The agent seems to “forget” and says it needs to start a session
Why: Every conversation begins by loading the site’s current rules and instructions — a step called bootstrapping. That proof expires after a couple of hours, so in a long session the agent occasionally has to re-bootstrap.
Fix: Nothing — this is normal and self-correcting. The agent re-runs the step automatically and carries on; you may notice a brief extra step, no more. See Abilities & Sessions.
The agent says it’s being rate-limited
Why: To protect your site and your AI credits from a runaway loop, Maxi caps how many actions an agent can take per minute, in tiers (reads are generous, writes moderate, AI generation tighter). A burst of activity can briefly hit the cap.
Fix: Wait the few seconds the message indicates and the agent continues. If you hit it constantly during legitimate bulk work, the limits are adjustable by a developer via your site configuration.
Missing or unavailable features
WooCommerce, Analytics, or SEO actions aren’t available
Why: These capabilities depend on another plugin being active. WooCommerce abilities need WooCommerce; Analytics needs the Maxi Web Analytics plugin; SEO (term fields) needs Yoast SEO. If the plugin isn’t active, the related actions simply aren’t available and the agent will say so.
Fix: Activate the required plugin. The conversions analytics report additionally needs WooCommerce on top of Maxi Web Analytics. See Agent Capabilities for which domains depend on what.
AI text or image generation fails
Why: AI generation runs through an external provider (OpenAI, Anthropic, and others), which needs an API key. Without a key for the relevant provider, generation can’t run.
Fix: Add a provider API key, then retry. See Add and Rotate Provider API Keys. If a key is set but generation still fails, the key may be invalid or out of credit — rotating in a fresh key validates it with a live test.
The agent says the installation isn’t complete or rules aren’t installed
Why: Maxi ships a set of baseline operating rules that should install automatically on activation. Very occasionally — after an unusual update path — a rule can be missing.
Fix: Ask the agent to sync the rules (it has a one-step action for this), or deactivate and reactivate the plugin. If it persists, contact support.
Licensing
An action says my plan doesn’t include it
Why: The feature belongs to a group your current plan doesn’t cover.
Fix: Upgrade your plan at maxicore.ai. The change applies on the next license refresh — up to 12 hours, or immediately if you re-check the license under Settings → Maxi AI → License. See Licensing & Entitlements.
Everything suddenly stopped working
Why: Usually licensing. When a license expires, abilities keep working for a 7-day grace period with a warning, then stop. A deactivated license has the same effect immediately.
Fix: Check your license status (ask the agent, or look under Settings → Maxi AI → License) and renew or reactivate. See Licensing & Entitlements.
Data & privacy
The agent only sees redacted customer data (like “J*** D**”)
Why: That’s data masking doing its job. Maxi redacts personal-data fields before they reach the agent, on by default, for privacy.
Fix: Nothing if you want the protection. If a specific field is being masked that you’d rather wasn’t, you can adjust the masking list. See GDPR Data Masking.
Is my data safe? What can the agent actually see and do?
An agent can do only what the WordPress user it’s connected as is allowed to do, and content changes require an administrator. Personal data is masked by default before it reaches the agent. Every change the agent makes is recorded in a tamper-evident audit log you can review. For the full picture, see the Security Model and Read the Audit Log.
Can the agent delete things or do something irreversible?
Destructive actions are gated behind administrator access, and a good practice is to scope your agent’s user to only what it needs. The agent is also guided to prefer safe paths — for example, creating content as a draft for your review rather than publishing immediately, and archiving rather than deleting where possible. If you want a strictly hands-off agent, connect it as a non-administrator: it becomes read-only. See Manage Agent Users.
General questions
Which AI does Maxi use?
Two separate things. The agent you talk to is whatever MCP-compatible AI client you’ve connected — Claude, ChatGPT, and others. Separately, Maxi’s own generation features (writing text, making images) call providers you configure with an API key: OpenAI, Anthropic, OpenRouter, Replicate, BFL, or a local model. See AI Generation.
Do I need to learn ability names or commands?
No. You talk to the agent in plain language and describe what you want; it picks the right actions. The ability names in this documentation are there so you understand what’s happening under the hood, not because you need to type them.
I’m still stuck
Two things help most. First, ask the agent to read the audit log — it often shows exactly what was attempted and why it was refused. Second, for technical and developer-level detail (error codes, configuration constants, connection internals), see the technical documentation at docs.maxicore.ai. For anything else, contact support via maxicore.ai.