WordPress Connector¶

The WordPress connector is a plugin that integrates your WordPress site with Patcherly for automated error detection and fixing.

WordPress sites: this plugin is the recommended way to connect a WordPress website/app (target). For non-WordPress websites/apps (PHP, Node, Python), use the Universal Installer instead.

Post-apply test execution and app restarts: not available on WordPress. The plugin only changes files on your site — it never runs commands on your server (this is a hard rule of the WordPress plugin directory, and a safety feature). If you need Patcherly to also run tests or restart your app after a fix, use a standalone Python, Node.js, or PHP connector instead — those run as separate programs and can be granted permission to execute commands. See App restart automation and Restarting apps.

What the plugin sends to Patcherly¶

The plugin talks to one external service: api.patcherly.com. It does not contact Patcherly when WordPress activates the plugin, when you switch themes, or on every page load.

• Before you click "Connect with Patcherly", the plugin sends nothing. No background calls, no pings.
• After pairing, when an error happens on your site, the connector sends the error details (message, file path, line number), a small snippet of the file around the error, and basic site information (your site URL and WordPress / PHP / plugin versions). It never sends your database, your media library, your user data, or your full site files.
• Site information for the AI (active plugins, theme, WooCommerce status) is uploaded when you click Refresh site context in Settings (or View collected context in Connector Status), once automatically right after pairing if you have already chosen Full or Minimal sharing, and on your next Patcherly admin visit after you activate or deactivate another plugin (when sharing is enabled).
• Your authentication credentials are stored encrypted in your WordPress database.

Early error capture (Rescue): Patcherly also installs a small emergency logger that can catch PHP fatals during plugin load — before your normal error log might record them. Those errors appear in the dashboard like any other error (with the same message format). If you use a custom log path, Rescue may still see errors in debug.log or its own emergency log that your custom file does not contain.

When you expand an error's full text in the dashboard or WordPress admin, Patcherly may append a short source line at the bottom so you can tell how it was captured:

• (Patcherly Emergency Logger) — the error was detected by Emergency Rescue while your site was down or the main plugin could not run (for example a white screen after a bad site update). Rescue still sent the log line to Patcherly so you could see the failure and roll back or approve a fix.
• (Patcherly Advanced Logger) — reserved for errors captured by the main WordPress plugin's normal log monitoring while your site is up (Settings → Advanced). Rescue-sourced errors use the Emergency label instead.

The table preview stays a short headline only; open the full error text to see the source line.

See Privacy Policy and Terms of Service for the full details.

Installation¶

Method 1: Manual Installation¶

1. Download the Plugin

2. Download the patcherly plugin zip from the dashboard or installer

3. Upload to WordPress

4. Navigate to your WordPress site's /wp-content/plugins/ directory

5. Upload the patcherly folder

6. Activate the Plugin

7. Log in to your WordPress admin panel
8. Go to Plugins → Installed Plugins
9. Find "Patcherly" and click Activate

Method 2: WordPress Admin Upload¶

1. Go to Plugins
2. Log in to WordPress admin

3. Navigate to Plugins → Add New

4. Upload Plugin

5. Click Upload Plugin
6. Choose the patcherly.zip file

7. Click Install Now

8. Activate

9. After installation, click Activate Plugin

Configuration¶

Step 1: Open Home¶

1. After activation, you'll see "Patcherly" in the WordPress admin menu (shield icon).
2. Click Home (or the top-level Patcherly menu item) to open the overview page.

Step 2: Connect the connector¶

To connect your site with your Patcherly account, click Connect with Patcherly on the Home page (or use the Connect button in the account status bar when not connected).

To disconnect and connect again, click Disconnect on Home when connected, then Connect with Patcherly again. If the account bar shows Connection lost — reconnect required, use Re-Connect Account in the Connect this site to Patcherly block (above Overview), then Connect with Patcherly.

Step 3: Settings (Optional)¶

Open Patcherly → Settings for advanced options, collected site context, and diagnostics. Connecting happens on Home, not Settings.

• Patcherly API endpoint: Defaults to https://api.patcherly.com. Don't change it unless Patcherly Support instructs you to.
• Errors Cache TTL: How long to cache error lists (default: 300 seconds).
• Cleanup on Uninstall: When enabled, removes all plugin settings and the wp-content/uploads/patcherly/ folder (including pre-apply backups) when you delete the plugin. See Deactivation vs uninstall.
• Demo submenu (default ON): show or hide the Patcherly → Demo (explore) submenu. Untick once you no longer need the demo.
• Debug Mode (optional, default OFF): see Debug mode below.
• Site context for the AI (default Off): choose Full, Minimal, or Off — see Context Collection for what each tier sends. Use View collected context to see exactly what would be shared and what Patcherly last stored.

Demo mode — explore without pairing¶

The Patcherly → Demo opens a demo Errors page with example WordPress / WooCommerce / generic-plugin errors in various states. This is a demonstration of what the Error page will look like, once you connect your Patcherly account with the plugin.

Use Demo mode to preview the connector UX before you pair a real site, or to walk a team member through the workflow without touching production data.

• No data leaves your server. The demo page never interacts with Patcherly servers, the data is just for test.
• No AI calls. Nothing is sent to any language-model provider.
• No database writes. State lives in sessionStorage (per browser tab), not in your site's database. Closing the tab resets the demo.

Once you don't need it anymore, you can hide the Demo (explore) submenu by unticking Demo submenu in Settings → Advanced settings (default is ON).

The Demo and live Errors tables share the same columns, row-action icons, and two footers under the table: an action-icon legend and a status-badge legend (same labels and colors as the Status column — Analyzed, Ready to Patch, and Manual review use the same blue analyze tone; Suspicious is a separate red quarantine flag; waiting badges keep their stage color with a short pulse or spin — apply green, rollback amber, analysis sky-blue). Ongoing action icons (Waiting for connector / In progress) use the same stage colors with a pulse and no fill background. Each legend includes a small Help link for more detail. Dashboard legends also collapse to a short preview with Show all; the WordPress plugin legends stay fully expanded. Excluded path-rule rows appear slightly faded; use Hide Error & Ignore to remove them from the default list. Hover any row icon or badge for the full tooltip. Above the table, Filters (collapsed by default) and Columns sit in the toolbar next to bulk actions — same pattern as the Patcherly dashboard.

When your site won't load¶

If a theme or plugin fatal leaves WordPress showing a blank screen, the normal Patcherly plugin may not load — but Rescue mode can still help.

flowchart TD
    A[A theme or plugin causes a PHP error] --> B{Can the main Patcherly plugin still run?}
    B -->|Yes| C[Errors are logged and sent to Patcherly]
    B -->|No — blank or broken site| D[Rescue must-use plugin runs early]
    D --> E[Rescue logs the error and can roll back or apply fixes]
    C --> F[You see the error in Patcherly and can approve a fix]
    E --> F
    F --> G{Fix made things worse?}
    G -->|Yes| H[Rollback restores files from your local backup folder]

When even Patcherly cannot help (rare): if PHP crashes inside wp-config.php before WordPress starts, if another must-use plugin crashes before Rescue loads, or if you deleted the local backup folder — Rescue cannot capture errors or roll back. Use your hosting provider's snapshot or restore files manually from wp-content/uploads/patcherly/backups/.

On pairing, Patcherly prepares storage under wp-content/uploads/patcherly/ (backups, locks, queue, emergency log, and a cache/ subfolder for local AI context JSON). The plugin writes Apache .htaccess and IIS web.config deny files in those folders (including nested backup and cache dirs). Tools → Site Health, Settings → Diagnostics, and an admin notice warn if a canary URL returns HTTP 200 (common on Nginx without a deny rule). Optional PATCHERLY_BACKUP_ROOT moves backups only — queue, fix-cache, locks, and emergency.log stay under uploads/patcherly and still need a vhost deny on Nginx (see Connectors overview). Right after pairing, the Home page shows a short onboarding card where you choose site context for the AI (Full / Minimal / Off) and confirm Emergency Rescue (recommended, on by default). Click Get started — that is your explicit consent; nothing is installed or uploaded until you confirm.

Emergency Rescue copies one small must-use file (000-patcherly-rescue.php) into your must-use plugins folder so Patcherly can still reach your site when the main plugin cannot load — for example after a plugin update that causes a white screen. Without it, Patcherly may not be able to roll back or restore your site in that emergency. You can turn Rescue off later in Settings → Advanced.

Did you know? The Patcherly WordPress plugin is loaded by WordPress in the same PHP process that serves your site — just like any other plugin. A fatal error in your theme or another plugin can white-screen the site and stop the main Patcherly plugin (and all other plugins) from running normally. Emergency Rescue solves that in-process coupling: it is a must-use (MU) plugin that loads earlier than regular plugins, so it can still log errors, apply approved fixes, and run rollbacks you trigger from the dashboard even when the main plugin — or the site itself — cannot load. Patcherly built it to stay crash-independent because WordPress loads plugins in a fixed order, and a broken plugin update is one of the most common ways sites go down.

Rescue then:

• Writes PHP errors to wp-content/uploads/patcherly/emergency.log and tails wp-content/debug.log when enabled
• Sends new log lines to Patcherly even when the main plugin cannot run
• Picks up Rollback requests from the dashboard and restores files from your local pre-apply backups
• Applies approved fixes when the main plugin is down (same backup + verify flow)

wp-config bootstrap (recommended): In Settings → Advanced, copy the snippet that enables WP_DEBUG_LOG into wp-config.php. To allow a one-click write, enable Allow Patcherly to write the snippet… and click Apply snippet now — never automatic on pairing.

From the Patcherly dashboard: open Targets, expand your WordPress site, and click Run rescue now to ask Rescue to detect logs, roll back, or apply immediately — useful when your host has no cron.

How rollback is coordinated: after a failed health check, Patcherly sets the error to rolling back and pings Rescue on WordPress targets only. If the main plugin is still alive, its own rollback cron runs first; Rescue steps in only when the main plugin cannot load or has gone quiet. Both paths use the same on-target backups and a file lock so they cannot fight over the same restore.

Limits: Rescue cannot run if PHP dies inside wp-config.php before WordPress loads, if another must-use plugin fatals first, or if you deleted the local backup folder. In those cases use your host snapshot or restore files manually from wp-content/uploads/patcherly/backups/. On a VPS where must-use plugins are disallowed, the PHP connector on the same host can fill a similar role — it polls on a schedule without needing wp-admin visits.

Managing the connection¶

Once your site is paired, the plugin keeps a secure connection open to Patcherly. Every fix it receives is verified before being applied, and every message it sends to Patcherly is signed so the server knows the request really came from your site. Failed calls are retried automatically.

Reconnecting¶

If credentials need a full re-pair (plugin shows Connection lost / dashboard Re-auth required):

1. Prefer Auto-Reconnect on the Targets row in the Patcherly dashboard (opens this plugin’s settings for guided reconnect), or
2. On the site: Patcherly → Settings → Disconnect, then Connect with Patcherly again.

Temporary network blips show Reconnecting… on Targets while Patcherly is actively retrying (or while you run Auto-Reconnect). The badge hides between scheduled waits and after retries stop — you usually do not need to Disconnect.

Agent offline (stale or inactive presence after a prior pairing) is different from Reconnecting…: the connector has not checked in recently. Use Auto-Reconnect to restore a live session. Never-paired sites show Pair site / Connect instead of Agent offline.

"This site isn't paired" notice¶

If you open Patcherly → Errors before pairing — or after your site has been removed from your Patcherly account — the Errors page shows a friendly notice at the top with a one-click link back to Home to (re)connect.

Supported Applications & File Types¶

✅ Supported Applications¶

The WordPress connector is designed specifically for WordPress websites:

• WordPress Core - Standard WordPress installations
• WordPress Multisite - WordPress network installations
• WordPress with Custom Themes - Any WordPress theme
• WordPress with Plugins - Any WordPress plugin
• Custom WordPress Applications - WordPress-based websites, blogs, e-commerce sites

✅ Supported File Types¶

The connector can patch and validate syntax for:

• .php - PHP files (themes, plugins, WordPress core files)
• .phtml - PHP template files

What gets patched: - WordPress theme files (/wp-content/themes/) - WordPress plugin files (/wp-content/plugins/) - Custom PHP files in your WordPress installation - WordPress core files (if you have write permissions)

❌ Not Supported¶

Other file types: - JavaScript files (.js) - Client-side JavaScript is not patched - CSS files (.css) - Stylesheets are not patched - Other languages (Python, Node.js, etc.) - Database content - The connector patches code files, not database entries

Note: Before applying a fix, the plugin snapshots all existing paths in the patch into your local backup folder under wp-content/uploads/patcherly/backups/. The plugin checks the modified files for syntax errors before and after applying a fix. It's purpose-built for WordPress and can also share WordPress-specific information (active plugins, theme, etc.) with the AI to produce better fixes — see Context Collection below.

For non-WordPress PHP applications: Use the PHP Connector instead.

Features¶

Error Management¶

• View errors — browse, filter by status, severity, or language.
• Bulk delete — select multiple errors and remove them in one click when they were never applied (noise, ignored rows, pre-fix workflow). Delete is not available for successfully patched errors or any row after a patch apply attempt — use Hide Error & Ignore for list cleanup instead; older rows are pruned by audit retention. Delete is permanent (there's no trash), does not undo fixes on your site (use Rollback for that), does not refund quota, and does not touch connector backups on your server. Your dashboard metrics stay accurate.
• Live updates — the errors list refreshes automatically.
• Detailed view — full error message, stack trace, file snippet, and the patch preview.

Fixes, confidence, and plan limits¶

The plugin applies patches you approve in wp-admin or the dashboard. Low-confidence fixes may require explicit confirmation in the dashboard before apply — the plugin shows a notice when that gate is active. Auto Apply and Auto Analysis controls follow your workspace plan and dashboard policy; the plugin mirrors those limits in its UI.

See Approving fixes and Path rules for targets.

Context Collection¶

The plugin can share a small amount of information about your WordPress install with Patcherly so the AI can suggest better fixes. You're in charge: nothing is shared until you pick a tier.

Right after pairing, the Home page shows an onboarding card: pick Full, Minimal, or Off for site context, confirm Emergency Rescue (recommended), then click Get started. You can change either choice any time in Settings → Advanced settings.

Privacy: Patcherly does not collect or store your database, user accounts, or site content. Only technical information about your install (versions, and optionally plugin/theme names) is shared when you choose Full or Minimal and click Refresh site context.

• Full — share your active plugins, theme, custom post types, WooCommerce status, and server / database info. Recommended for the best AI suggestions.
• Minimal — share only the WordPress version, PHP version, and database version. Nothing about your installed plugins, themes, or content.
• Off (default) — share nothing. The AI sees only the error message itself. A good starting point if you want to begin carefully and upgrade later.

Nothing is uploaded on activation, theme change, or every page load. After you click Get started with Full or Minimal, the first context upload runs once automatically. You can also click Refresh site context in Settings any time later. When you activate or deactivate another plugin, the connector notes the change locally and uploads an updated snapshot on your next visit to Home, Settings, or Errors (no outbound call on the activation hook itself).

Why sharing context helps: - More accurate AI fixes, tailored to your environment. - Better understanding of how your plugins and theme interact with the bug. - Fewer rounds of back-and-forth before a fix lands.

Where your choice is stored: in your own WordPress site (your site's options). The plugin re-reads it before every upload — if you switch to Off, the next Refresh site context click stops and tells you where to switch it back on.

View collected context: On Home (Connector status → Context sharing row) or Settings → Site context for the AI, click View collected context → to open the collected-site-context panel. It shows a live preview of what this site would share at your current tier and, when paired, the last copy stored on Patcherly after an upload.

Home overview (metrics and audit)¶

When the site is not connected or sign-in expired, the Connect this site to Patcherly pairing block appears above the Overview metrics cards.

The Home page shows a 30-day metrics preview for your paired site when your plan includes advanced analytics (Core, Pro). Personal plans see sample numbers with an upgrade link to billing. Money saved and usage counts use the display currency and number format from your dashboard Profile → Preferences (formatting only — the underlying values come from Patcherly). View full metrics on dashboard → opens the Patcherly metrics page scoped to this target.

A usage limits bar (Fixes used counts billable AI analyses this billing period; Targets and Users vs plan caps) and Workspace name appear in the account status area when connected. The reset line reads Usage resets on <date> for your current billing period.

The Errors analyzed card counts errors where AI analysis completed on this site (still-pending errors and analysis that could not finish for technical reasons are excluded). It is not the same counter as Fixes used — the usage bar is workspace-wide and tied to your plan billing window. Hover the ⓘ icon beside any usage or metric label for a short explanation.

Recent audit events (last 5 workflow events for this site) appear in a table below the metrics cards with an Actor column (resolved name or system label). View full audit log on dashboard → opens the Patcherly audit page scoped to this target. Empty state: No audit events yet for this site.

Custom Log Paths¶

If your plan includes Advanced Error Monitoring (Core, Pro — see Pricing page), you can configure custom log paths:

1. Access Log Paths: Go to Targets → [Your Target] → Log Paths
2. Add Log Path: Click "Add Log Path" and enter the absolute path to your log file
3. Enable/Disable: Toggle log paths on or off as needed
4. Automatic Monitoring: Connector automatically monitors all enabled log paths

Example Log Paths: - /var/log/wordpress/error.log - /var/log/php/error.log - /home/user/logs/app.log

Requirements: - Custom log paths require the Advanced Error Monitoring plan feature — see the Pricing page for plan availability. Without it, the connector monitors the preset WordPress / PHP log locations only and the Add Log Path button is hidden.

Connector Management¶

Status Monitoring (after pairing): - Dashboard shows connector connection status. - Displays last connected timestamp. - Shows connection health indicators.

Initiation from Dashboard: - The dashboard walks you through installing the plugin and clicking Connect with Patcherly in WP-Admin. - Pairing happens in one click — no API key to copy or paste.

Connector Status¶

The Connector Status panel is on Home, inside a collapsed Connector status section at the bottom of the page. It tells you at a glance whether your site is in good shape:

• Plugin version — which version of the Patcherly plugin you have installed. Always shown, even before pairing, so support knows which release you're on.
• API — is the Patcherly server reachable from your site.
• Authentication — whether your connection to Patcherly is active (the plugin transparently rotates the access token a few seconds before it expires on every call to Patcherly, so you never need to manually reconnect on a schedule) or expired (which only happens if the refresh credential itself was revoked from your Patcherly dashboard — in that case click Disconnect, then Connect with Patcherly again to re-pair). To keep the connection alive on quiet sites that don't see errors for days, the plugin schedules a small daily check-in (via WordPress' built-in scheduled tasks) that just says "hello" to Patcherly so your credentials never age out. You don't need to do anything to enable it.
• Scopes — the permissions this connector was granted at pairing time (e.g. ingest patch audit files). These are locked to the original device-code grant and never change for the life of the connection.
• Secure signing — whether every message between your site and Patcherly is being cryptographically verified (always Enforced once paired).
• Workspace — which Patcherly workspace this site is paired to.
• Plan — your workspace plan name (Personal, Core, Pro) with a link to billing to upgrade limits and features.
• Target — the website registered on your Patcherly account, and whether it's still active. If you've removed the site from your dashboard, the Errors page shows a one-click "Reconnect" notice.
• Last connected — the most recent time Patcherly heard from this site.
• Test Mode — whether the per-target Test error window is currently open in your Patcherly dashboard. While it's ON, the Send Sample Error button works and any synthetic events sent from this site are tagged as samples so they don't pollute your real metrics or fire notifications.
• Monitored paths, Excluded paths, Patch exclusion paths — live values from your Patcherly target, each with a Customize button that opens the dashboard (upgrade link with a ⚡ icon when your plan lacks the feature).
• Context sharing — your Full / Minimal / Off tier, a link to change it in Settings, and View collected context → to inspect the snapshot panel.

Before pairing, every row that depends on the connection shows "Site not connected yet, pair it with Patcherly to run Diagnostics". The plugin will not call Patcherly on its own until you click Connect with Patcherly on Home. If you want to confirm Patcherly itself is up before pairing, expand Connector status on Home and click Refresh — that's the one and only call the unpaired plugin makes, and only when you click it.

Test Connection¶

Test your connection to the Patcherly server:

1. Go to Patcherly → Settings
2. In the Diagnostics card click "Test Connection"
3. View connection status and diagnostics

Send Sample Error¶

Test that error reporting works end-to-end without polluting your real metrics. Test events only flow while you've explicitly opened a Test Mode window from your Patcherly dashboard — this gate prevents an exposed connector credential, a curious script on your site, or a stray click from spraying synthetic traffic into your real error feed and triggering notifications. The window is per-target and lasts 30 minutes; you stay in control.

1. In your Patcherly dashboard go to Targets, click this site, and flip the Test Mode toggle ON — this opens a 30-minute window for this target only.
2. Back in WordPress, go to Patcherly → Settings → Diagnostics and click "Send Sample Error".
3. A synthetic event is sent and shows up in your Patcherly dashboard under Errors, flagged as a sample.

The plugin's Connector Status panel already tells you whether Test Mode is On or Off (the Test Mode row), and the Off state is a one-click link to the dashboard toggle. If you press Send Sample Error while it's Off, the diagnostic row will surface an Enable test error in Patcherly → link that opens the dashboard at the exact toggle — no traffic is sent.

Debug mode — share what your site asked Patcherly¶

Debug Mode is an opt-in local diagnostic surface designed for support escalations. It is OFF by default. When you turn it ON in Settings → Advanced settings, the plugin captures sanitized metadata about every API call it makes and lists them on a new Patcherly → Debug submenu.

What is captured¶

For each call the plugin made: when it happened, what it was for (e.g. "checking pairing status", "loading the errors list", "reporting a fix result"), the request method and URL, the HTTP status code, how long it took, and the error message if it failed.

What is NEVER captured¶

• Your authentication credentials or signing keys.
• The contents of any request — source-code snippets, AI prompts, settings.
• The contents of any response — AI-generated patches, error details.

Where the data lives¶

• On your own WordPress site only — in your site's database, capped at the most recent 200 entries (older ones drop off).
• Never sent to Patcherly. The Debug page itself does not make any outbound calls.

How to clear it¶

• Turning Debug Mode OFF in Advanced settings immediately deletes the option from your database.
• The Debug page also has a "Clear log" button.
• Uninstalling the plugin always deletes the option (even when Cleanup on Uninstall is off, this specific debug data is purged for safety).

For support reps¶

Ask the user to turn Debug Mode on → reproduce the issue → open Patcherly → Debug → click Copy as JSON → paste the JSON into the support ticket. Once triage is done, ask them to turn Debug Mode off to clear the captured entries from their database.

Security¶

• Encrypted credentials. Your authentication credentials are stored encrypted in your WordPress database — never as plain text, and never in any plugin file. A database-only leak cannot read them.
• Signed messages. Every message between your site and Patcherly is cryptographically signed and verified at the other end. Tampered or replayed messages are rejected automatically.
• No way to disable signing. Fix payloads without a valid signature are refused — this protects you from someone trying to push a malicious patch to your site.
• Revoke any time. Click Disconnect in the plugin settings to invalidate your current credentials. To rotate them, click Disconnect and then Connect with Patcherly again. Clicking Disconnect while your credentials are still healthy also tells the Patcherly server, so your dashboard's Targets page flips this site to inactive right away instead of waiting up to a week for the connection clock to age out. If your credentials are already expired when you click Disconnect (the "Connection lost" case below), the plugin still wipes the local copy and you simply re-pair to flip the dashboard back to healthy.

Troubleshooting¶

"API server unavailable"¶

• Check that your site can reach api.patcherly.com (your hosting provider or firewall may be blocking it).
• Make sure your site is served over HTTPS.

"Authentication failed" or "token expired"¶

• Click Disconnect, then Connect with Patcherly again.
• Make sure the Patcherly user account you used during pairing still has access to this site (your dashboard's Targets page should still list it).

"Connection lost — your sign-in expired and could not auto-renew"¶

This banner appears on the plugin Settings page when the plugin still has your sign-in saved on disk, but the Patcherly server rejected the most recent silent refresh. It usually means the site went quiet for long enough that the refresh credential aged out (the plugin schedules a daily check-in to prevent this — but a site with no front-end visitors and no admin logins for 30+ days in a row can fail to fire WordPress' built-in scheduled tasks at all, which is what allows the credential to expire). You'll see the same situation reported three ways at once:

• Plugin Settings page: red "Connection lost — your sign-in expired and could not auto-renew" banner.
• Connector Status panel: OAuth row reads "Connection lost — please reconnect".
• Your Patcherly dashboard's Targets page: the row shows Re-auth required / Not apply-ready — use Auto-Reconnect (or Disconnect then Connect in the plugin).

To fix it, prefer Auto-Reconnect on the Targets row, or click Re-Connect Account in the Connect this site to Patcherly block on Home (or the same control on Settings when the connection-lost notice appears), then Connect with Patcherly again. The dashboard target clears reconnect state within a few minutes of the first successful API call from your re-paired site.

"Signature mismatch"¶

• Click Disconnect, then Connect with Patcherly again to get a fresh credential.
• Check that your server's clock is correct (this is rarely the issue, but worth checking if everything else is fine).

"This endpoint requires HTTPS"¶

• Make sure your WordPress site is served over HTTPS.
• If your site sits behind a reverse proxy (nginx, Cloudflare, etc.), make sure that proxy tells your WordPress install that the original request was HTTPS. Without it, your site may think requests are HTTP, and Patcherly rejects HTTP. Most managed WordPress hosts handle this for you.

"Retry Patch" or rescue ping blocked (HTTP 403, "Just a moment…")¶

When you approve a fix or click Retry Patch, Patcherly sends a signed POST from our API to your site:

https://yoursite.com/wp-admin/admin-ajax.php?action=patcherly_rescue_poll

If Cloudflare Bot Fight Mode or a WAF rule treats that server-to-server request as a bot. The dashboard will show a dispatch failure until the edge allows the request through.

Patcherly has applied with Cloudflare as a signed agent using Web Bot Auth (User-Agent: Patcherly-RescuePing/1.0, key directory on api.patcherly.com). After Cloudflare approves the bot, edge verification may improve on paid Bot Management plans — Free Bot Fight Mode may still block rescue until Cloudflare confirms otherwise or you turn Bot Fight Mode off.

Cloudflare Free — Bot Fight Mode must be off

On the Free plan, Bot Fight Mode cannot be bypassed with WAF Skip rules, Configuration rules, or IP allow/skip rules in our testing (Cloudflare’s own docs are inconsistent on exceptions). If Security → Events shows Service: Bot Fight Mode for action=patcherly_rescue_poll, the reliable fix today is:

1. Security → Settings (filter Bot traffic) → turn Bot Fight Mode off.
2. Re-test with Retry Patch or Run rescue now on the target.

You do not need to disable all Cloudflare security — only Bot Fight Mode on Free. Other WAF managed rules can stay on. If you need bot fighting and Patcherly rescue apply without turning Bot Fight Mode off, upgrade to Pro or higher and use Super Bot Fight Mode with the Skip rule below.

Cloudflare Pro+ — Super Bot Fight Mode + Skip rule

On paid plans, Super Bot Fight Mode runs on the WAF Ruleset Engine, so scoped Skip rules can work (Super Bot Fight Mode docs):

1. Security → Settings (filter Bot traffic) → turn Bot Fight Mode off.
2. Turn Super Bot Fight Mode on.
3. Add the WAF custom Skip rule below (include All Super Bot Fight Mode Rules in the Skip targets).

Configuration rule (Browser Integrity / Under Attack only)

If events show Browser Integrity Check or I'm Under Attack (not Bot Fight Mode), add a Configuration rule with the same filter expression as below and turn Browser Integrity Check off for matching rescue requests. This does not bypass Bot Fight Mode on Free.

WAF Skip rule (Pro+ with Super Bot Fight Mode, or general WAF blocks)

1. Security → Security rules → Create rule → Custom rules.

Click Edit expression, then copy and paste the following rule into the dedicated space:

(http.request.uri.path contains "/wp-admin/admin-ajax.php" and http.request.uri.query contains "action=patcherly_rescue_poll" and http.request.method eq "POST" and any(lower(http.request.headers.names[*])[*] eq "x-patcherly-signature"))

Then under Choose action, select Skip and enable:

• All managed rules
• All Super Bot Fight Mode Rules (only effective when Super Bot Fight Mode is on — not Bot Fight Mode on Free)
• Browser Integrity Check
• Security Level
• All rate limiting rules.

Place the rule First so it runs before blocking rules.

1. Configuration rule (optional) — only if step 1 is not enough and events are not tagged Bot Fight Mode:

Go to Rules → Overview → Create rule → Configuration Rule.

Use the same expression as above. Turn Browser Integrity Check off (dark grey, not green). Same for I'm Under Attack if enabled. Place the rule First.

1. Confirm Under Attack Mode is not blocking admin-ajax for unauthenticated POSTs.

If rescue dispatch fails but the main plugin is healthy

Rescue is the fast path (especially when the main plugin cannot load). The WordPress connector also picks up approved fixes on its normal poll when someone visits Home, Settings, or Errors in wp-admin — that traffic is outbound from your server to Patcherly and is not the same as the inbound rescue ping Cloudflare blocks.

If rescue is blocked, Retry Patch in the dashboard may keep showing a dispatch error — open Patcherly → Errors in your WordPress admin and click Retry Patch there; the connector fetches the fix from Patcherly (outbound) and applies it on your server without a rescue ping. The connector warms the local cache when you load the Errors page. Cached signed fix payloads live under wp-content/uploads/patcherly/cache/pending-fixes/. When edge protection blocks dispatch, Approve patch or Retry Patch in wp-admin can auto-fetch into that cache, apply on-server in the same request, and report the result to Patcherly (apply-result) so the error moves to Fixed on the dashboard. If the fix is already on disk and edge is still blocked, retry is idempotent and only syncs status. The connector syncs an edge rescue blocked flag from Patcherly on heartbeat and when the Errors page refreshes.

Local cache notes

• Cache files are not web-served (same protection as other Patcherly uploads storage).
• Every cached patch is re-verified with HMAC before apply; tampered or expired cache (7 days) is rejected.
• Cache is cleared after successful apply, reject patch, mark fixed, delete, or rollback.

After changing Cloudflare settings, wait a minute for propagation, then use Retry Patch on the error or Run rescue now on the target.

General fixes¶

• Reconnect — Disconnect, then Connect with Patcherly again. This fixes most credential and trust issues.
• Clear the errors cache — temporarily set the cache to 0 in Advanced settings, then reload the Errors page.
• Check your WordPress error log — your hosting control panel usually has a "Logs" or "Error log" section.
• Status page — check the Patcherly status page if multiple sites are showing the same problem.

Deactivation vs uninstall¶

Tip: click Disconnect in the plugin settings before uninstalling if you want the target removed from your Patcherly dashboard right away.

The optional wp-config.php debug snippet (if you added it) is not removed automatically — edit wp-config.php yourself if you no longer want WP_DEBUG_LOG.

Uninstallation¶

Standard uninstall¶

1. Go to Plugins → Installed Plugins
2. Find "Patcherly"
3. Click Deactivate (optional but recommended first)
4. Click Delete

Cleanup option¶

If Cleanup on Uninstall is enabled in Settings → Advanced before you delete the plugin:

• All plugin options and cached credentials are removed
• The wp-content/uploads/patcherly/ folder is deleted (backups, locks, queue, emergency log)

If cleanup is off, your settings and on-server backup folder remain until you delete them manually.

Plugin updates¶

While the plugin is awaiting approval on the WordPress.org plugin directory, you upgrade it manually:

1. Download the latest patcherly.zip from Patcherly-Official/patcherly-connector-packages Releases.
2. In WordPress, go to Plugins → Add New → Upload Plugin.
3. Pick the new patcherly.zip and click Install Now.

WordPress replaces the previous version in place — your settings, your pairing, and your connection to Patcherly are preserved. Once the plugin is approved by WordPress.org, updates will arrive automatically on your Plugins screen, just like any other directory plugin.

The plugin does not update itself from the Patcherly dashboard. This is intentional — the WordPress.org plugin directory does not allow plugins to fetch updates from external sources.

Translations¶

The plugin's admin interface is ready for translation, and WordPress will automatically use the right language based on your Settings → General → Site Language choice (or your user profile's preferred language).

What ships in the plugin:

• A translation template you can use to create translations into your own language.
• An Italian translation, ready to use.

Adding a new language:

1. Open the translation template (patcherly.pot, inside the plugin's languages/ folder) in Poedit — a free, friendly translation editor.
2. Save it as patcherly-<your-locale>.po (e.g. patcherly-de_DE.po for German).
3. Translate the strings, then save — Poedit will write the matching .mo file next to it.
4. Drop both files into your site's wp-content/languages/plugins/ folder.

If you want to contribute your translation back so it ships with the plugin for all users, open a pull request on GitHub.

Support¶

For additional help:

• Check the troubleshooting guide.
• Review your WordPress error logs.
• For credential or sync issues, click Disconnect in the plugin settings, then Connect with Patcherly again.
• Open Support from the bottom of the dashboard sidebar if you're stuck.

Next Steps¶

• Understanding errors
• Approving fixes
• Managing your targets