Troubleshooting

A customer says they emailed twice and heard nothing. Or your reply shows on the ticket but never reached them. Support problems hurt more than most plugin bugs, because the customer only sees silence.

Most Core Support problems come down to a short list of causes:

• WP-Cron isn’t running
• a mail setting is still on its safe default
• a credential no longer matches
• a message is waiting for review

This page goes through them in the order I’d check them.

Start with Diagnostics

Open Core Support → Diagnostics or run wp core-support doctor. Read the detail line of every check, not just the badges. The Mail queue, Mail delivery, IMAP polling and Attachment storage checks point straight at many of the problems on this page.

The Plugin Won’t Activate or Run

• “Core Support requires WordPress 7.0 and PHP 8.2 or newer. It is installed but not running.” Upgrade PHP or WordPress. Core Support stays installed but does nothing until both meet the minimum.
• “Core Support is missing its bundled libraries. Reinstall the plugin from its release package.” The plugin was installed from a source checkout or an incomplete upload. Install the release ZIP.
• “Activate Core Support on an individual site, not network-wide.” Core Support doesn’t support network activation. Activate it on each site that needs a help desk.
• “Saving credentials requires the PHP sodium extension.” Ask your host to turn on sodium. It’s part of standard PHP builds, but some hosts leave it out.

“Core Support Setup Failed” Notice

The notice reads “Core Support setup failed. Ticket changes and mail are paused. Check Diagnostics and repair the database.” Core Support couldn’t create or upgrade its tables, so it pauses ticket changes and all mail work rather than lose anything. Mail routes answer 503, which relays and automation tools retry later.

Core Support tries again on every request. Check the Ticket schema line on Diagnostics, then look at what’s blocking table changes, such as a database user without CREATE or ALTER rights. Core Support needs InnoDB tables and refuses to run on tables that are missing or use another engine.

Email Arrives but No Ticket Appears

First check Core Support → Incoming mail. Email that didn’t become a ticket usually sits there with a reason:

• New sender: the address has no earlier conversation, so it waits for an agent. Choose Accept as new ticket, or set Email from new senders to Open a ticket automatically.
• Conversation not matched: a reply with a reply token that doesn’t match a ticket. See the reply section below.
• Automatic mail, Delivery report, Bulk email or Repeated automated message: filtered on purpose. These never open tickets.
• Larger than the mailbox limit: raise the mailbox’s size limit. It’s capped at 10 MiB while files are stored in the database and at 25 MiB with external storage.
• New tickets are paused or This ticket is closed: your ticket settings refused it.
• Queued for more than a few minutes: received but not processed, so WP-Cron probably isn’t running.

If nothing reaches Incoming mail at all, the problem is before Core Support: the relay, the mailbox or the automation tool.

WP-Cron Isn’t Running

Core Support processes mail, sends replies and syncs changelogs on WP-Cron, which runs only when someone visits the site. A quiet support site can hold mail for hours, and the Mail queue check fails once anything waits longer than 10 minutes.

Add a server cron that runs every minute:

* * * * * cd /path/to/wordpress && wp cron event run --due-now --quiet

To push the queue through right now, run wp core-support mail-run.

Relayed Mail Never Arrives

• Your relay Worker is older than 0.9.1. Earlier Workers failed every delivery on Cloudflare. Redeploy it from the 0.9.1 package or a later one. Nothing changes in WordPress.
• 401 with “The relay signature could not be verified.” The Worker’s secret doesn’t match the mailbox’s relay secret, or the server clock is more than 5 minutes off.
• 404 with “No mailbox uses this address. Check the webhook URL.” The Worker points at the wrong route key or the mailbox was removed.
• 413: the relay request is over 3 MiB.

Receive Support Email with Cloudflare Email Routing has the Worker setup.

IMAP Polling Misses Mail

• Old mail didn’t import. On the first connection, Core Support imports only unread mail, so old conversations don’t become tickets. After that it imports every new message, read or not.
• Microsoft 365 won’t connect. Microsoft turned off password sign-in for IMAP, and 0.9.2 doesn’t include OAuth. Use the Cloudflare relay or an automation tool for Microsoft 365.
• Gmail or Google Workspace refuses the password. Turn on 2-Step Verification and use an app password.
• A message stayed unread in the mailbox. It’s larger than the mailbox limit. Core Support lists it under Incoming mail → Connection details.
• “Message UID … was imported, but mailbox cleanup failed”: the message became a receipt, but marking it read or moving it to processed_folder failed. Fix the folder name or mailbox permissions. Later mail keeps importing.

Connection errors show under Incoming mail → Connection details and on the IMAP polling check. wp core-support mail-poll prints them straight away.

Automation Tool Requests Fail

• 401: wrong token. Copy it again from the mailbox on Core Support → Connections.
• 403: automation tools aren’t turned on for this mailbox.
• 413: the message is over the mailbox limit.
• 422: a field is missing or invalid, such as no from, a from that isn’t an email address or neither text nor html. Fix the mapping; retrying won’t help.
• 503: storage is unavailable. Retry later.

If your server strips the Authorization header, send the token as X-Core-Support-Token instead. A GET to the same URL tests the token without sending anything.

Customers Don’t Receive Replies

• Mail delivery is still Capture only. That’s the default, and nothing is sent. Choose WordPress mail or a provider API under Settings → Notifications → Mail delivery.
• Email customers about agent replies is off. New notifications are marked disabled and queued email pauses.
• The provider refuses the sender. Set Sender email to an address on a domain you verified with that provider. Resend and Emailit send only to your own account address until the domain is verified.
• Brevo blocks the server. Brevo accounts created since May 2024 block unknown IP addresses. Add your server’s IP under Security → Authorized IPs in Brevo.
• WordPress mail goes nowhere. WordPress mail hands each email to wp_mail(), so it arrives only if other WordPress email does. Fix that first, for example with an SMTP plugin such as FluentSMTP.

A rate limit or outage at the provider puts the email back in the queue, up to 5 attempts. Any other refusal marks it failed, and an agent can retry it from the ticket once the cause is fixed. The Mail delivery check shows the provider’s latest error from the last day. Send Replies through WordPress Mail or a Provider API covers each provider.

Customer Replies Land in Incoming Mail

A reply joins its ticket only when the reply token matches and the sender is the address the email went to. It waits in Incoming mail as Conversation not matched when:

• the customer replied from a different address, such as a work account
• the email they answered is older than 90 days, so its reply token expired

If replies bounce or never arrive at all, your mail service may not deliver plus-addressed mail (support+token@) to the main mailbox. Switch the mailbox’s reply tracking to Message headers. Header tracking can’t be used with the Emailit, Resend or Brevo API. Emailit sets its own Message-ID, Resend and Brevo don’t document keeping one, and Diagnostics fails that combination.

A wp-config Mailbox Is Ignored

Core Support → Connections shows a red notice naming the ignored mailbox, with the reason. The usual causes:

• a key with capitals or underscores
• a secret or token shorter than 32 characters
• a reply_address containing +

wp-config Constants lists every rule.

Attachment Storage Problems

• New files went to the database. A broken CORE_SUPPORT_STORAGE falls back to database storage for new files. The Attachment storage check names the problem. Until it’s fixed, Support Managers and administrators also see “Attachment storage needs attention.” on Core Support screens, with an Open Connections link.
• The Connections screen won’t switch providers. Existing files depend on the external destination they went to. So Core Support won’t change that destination’s provider, endpoint, bucket or zone. Credentials can still be rotated for the same location.
• Mail is refused with 503 during an outage. Core Support won’t store a message partly. The relay and IMAP poller retry it later, and automation tools should retry too.
• A downloaded bucket file won’t open. Files are encrypted before upload by default. Open them through Core Support.

Run wp core-support storage test after any change.

Saved Passwords Stopped Working After a Migration

If connections fail after moving the site, restoring a backup or running a security plugin, check whether AUTH_KEY or AUTH_SALT changed. Core Support’s encryption depends on them. With new salts, saved credentials read as empty, originals and encrypted attachments can’t be opened, connected site keys stop working and replies to old emails stop matching.

Restore the old salts if you have them. Otherwise enter every credential again and issue new site keys. Data, Privacy and Uninstall lists everything tied to the salts.

Docs Don’t Show on Another Website

• The frame stays blank. A server or CDN rule that sends X-Frame-Options on every page blocks it. Add an exception for /docs/ on the help-desk site.
• Only some collections appear. The frame shows only the collections ticked for that site. Collections that need sign-in can’t be embedded.
• The page isn’t one of the site’s addresses. Only the listed addresses may frame the docs. Add https://www. and the bare domain if visitors use both.

A Docs, Changelog or Support Page Shows a 404

Core Support refreshes WordPress’s permalinks after it installs or updates its address rules. If /docs/ or /changelogs/ still 404s, go to Settings → Permalinks and choose Save Changes. Check that no page or post already uses that slug.

The Chat Button Doesn’t Show

• Chat is off until you turn it on.
• The answer model’s provider has no API key. The button stays hidden until you add one, and the Chat screen warns about it.
• Where the button shows decides the pages. By default that’s Docs pages and Support portal pages. Never on these addresses wins over everything.
• Inside a docs frame on another website, the chat button stays off.
• On another website, “This website is not allowed to use this chat.” means the site isn’t set up under Core Support → Connected sites. It also appears when the page isn’t on one of that site’s addresses.
• When the daily token budget is spent, Chat stops calling the provider and offers a ticket instead.

Current Limits

• Microsoft 365 IMAP needs OAuth, which isn’t included yet.
• Customers can’t upload files from the portal. Attachments arrive by email, an automation tool or a server request.
• A connected site’s portal shows only tickets opened on that site, not tickets the same customer opened by email.

When You Ask for Help

Include these, with anything personal removed:

• your Core Support, WordPress and PHP versions
• the output of wp core-support doctor, or a screenshot of the Health checks tab
• the reason shown on the message in Incoming mail, if mail is involved
• the exact error text or HTTP status your relay, tool or browser received