Rollback¶

If a fix causes issues, Patcherly can automatically or manually rollback the changes. This guide explains how rollback works, when it happens, and what depends on your plan.

What is Rollback?¶

Rollback is the process of:

• Reverting changes made by a fix
• Restoring the original code from backup
• Returning to the previous state before the fix was applied

When Rollback Happens¶

Rollback can occur automatically (system-triggered) or manually (you trigger it). Manual rollback is available to all users on every plan.

Automatic Rollback¶

Patcherly automatically rolls back in these cases:

Basic health check failure (all plans)¶

After every fix is applied, Patcherly runs a basic health check for your website/app (target):

• The system sends a simple request to your website/app’s URL (from your target settings).
• Pass: Your site returns a normal response (2xx or 3xx).
• Fail: Your site returns a server error (5xx), is unreachable, or times out.

If the basic health check fails, automatic rollback is triggered on every plan—no upgrade or paid plan feature is needed. This protects you from a patch that breaks the site (e.g. PHP 500, runtime error, or the app no longer responding).

Timing. The basic health check runs within ~10 seconds of the connector confirming the apply on its side. If it fails, the rollback request is queued immediately and the status moves to Rolling back on the dashboard — the actual file restore then happens on the connector's next discovery pass (typically within ~30 seconds for PHP / Python / Node; WordPress may be immediate via Rescue ping or wp-admin rollback, otherwise on the next log-path poll or daily heartbeat — see Connector overview).

Enhanced checks (requires Agent Testing plan feature)¶

If your plan includes Agent Testing (see Pricing page for availability), you also get:

• Enhanced health check: Based on test execution (syntax, runtime, tests passed/failed). If the health score is critically low (<30), automatic rollback is triggered.
• Test failure: If a large share of automated tests fail after the fix, automatic rollback can be triggered.
• Syntax error: If the fix introduces a syntax error (detected by the connector), rollback can be triggered.

Summary¶

Fail-closed apply (unsupported patch format)¶

If the connector cannot parse the fix payload as a valid unified diff, it refuses to mutate any files and immediately restores the safety backup it took before parsing. The fix attempt is recorded as failed with reason: "unsupported_patch_format" and your target file on disk is unchanged. This protects you from corrupted or partial diffs (for example a CRLF-rewritten transport, or an unrecognised patch format). To recover, re-request analysis so a fresh diff is generated — retrying the same payload won't change the outcome. See Troubleshooting → Fix marked unsupported_patch_format.

Manual Rollback¶

Manual rollback is available to all users (every plan). Use it when you want to revert a fix yourself.

1. Go to Errors in your dashboard
2. Find the error with status Fixed or Failed
3. Click "Rollback" button
4. Select a rollback reason:
5. Patch didn't fix the issue – Error still occurs (recorded so similar bad fixes can be avoided later)
6. Patch caused new problems – Introduced new errors (recorded so similar bad fixes can be avoided later)
7. Personal or operational decision – Other reasons (neutral)
8. Other reason – General fallback
9. Optionally add comments
10. Confirm the rollback action

Your reason helps Patcherly recognize unsuccessful fixes in context. Manual rollback does not require a specific paid plan feature.

How Patcherly learns from outcomes¶

When a fix succeeds, fails, or you roll back a patch, Patcherly records the outcome (error signature, affected file path, the patch that did not work, and the reason) in your workspace's private, append-only outcomes log. That recording happens on every plan — outcomes always accrue so an upgrade lights up real history immediately.

On Core and Pro plans (the Patch Learning feature):

• When new AI analysis runs, Patcherly looks up prior successful and failed patches in your workspace that match the current error (by exact signature, then by a similar-error fingerprint) and includes a few of those examples as context for the AI. The model can then prefer approaches that worked for you and steer away from ones that did not.
• Core gets a smaller window (up to 3 prior examples per side, 90-day lookback); Pro gets a larger one (up to 5 prior examples per side, 180-day lookback).
• If a new suggestion is too similar to a past failed patch, the dashboard surfaces a warning so you are not stuck in a loop of repeated bad fixes.

On the Personal plan: outcomes are still recorded but prior examples are not injected into new AI analysis and the similar-failed-patch warning is not surfaced — this keeps token cost on Personal workspaces flat.

This is product logic inside Patcherly (pattern recognition and deduplication of known-bad suggestions). It is not the same as training third-party commercial AI models on your full codebase for general-purpose learning. Third-party models are used to analyze errors and generate suggestions; remembering what worked or failed for you is something Patcherly does with operational records tied strictly to your workspace and websites/apps (targets).

If you read elsewhere that Patcherly "improves over time," this is what that means on paid plans: remembering what did and did not work for your project, not reusing your code to train vendors' foundation models.

Rollback Process¶

When rollback is triggered (automatic or manual):

1. Target backup is verified: The connector checks the target backup — the pre-patch snapshot of the affected files on your own server.
2. Original code restored: Files are restored from that target backup
3. Status updated: Error status moves to Rolling back → Rolled back (success) or Rollback failed (critical)
4. Restart detection: System detects if application restart is required (for Python/Node.js applications)
5. Notification sent: You're notified of the rollback with restart instructions if needed
6. History recorded: Rollback is logged in error history

Status flow¶

• Rolling back: Rollback is in progress; wait for the final status. The connector on your server discovers this on its next poll or push path (typically within about 30 seconds for PHP, Python, and Node agents; WordPress may restore immediately when you roll back from wp-admin or via Rescue ping, otherwise on the next log-path poll or daily heartbeat), restores files from the on-server backup, then reports back so the dashboard can show Rolled back or Rollback failed.
• Rolled back: Rollback succeeded; you can re-analyze or approve again if needed.
• Rollback failed: Critical—restore could not be completed. The website/app (target) may be flagged for review; check the dashboard and contact support if needed.

Rollback safety net: if a fix sits in Rolling back for more than 30 minutes without the connector reporting back, Patcherly automatically moves it to Rollback failed with reason "timeout". This prevents fixes from being stuck forever when the connector process crashes, the host goes offline, or a scheduled task is skipped. Use Rollback from the Errors page to retry once the connector is back; the on-target backup is required for the manual retry to succeed.

Note: After rollback, you may need to restart or refresh your application for the changes to take effect — Python and Node.js apps typically need a process reload, and PHP apps may need a cache clear, OPcache reset, or composer dump-autoload. See Restarting Your Application for details.

Rollback Levels¶

Patcherly supports different rollback levels:

File-Level Rollback¶

• Restores individual files that were modified
• Other files remain unchanged
• Fastest rollback option

Service-Level Rollback¶

• Restores entire service/application
• Used for multi-file fixes
• May require service restart (see Restarting Your Application)

System-Level Rollback¶

• Complete system restoration
• Used for critical failures
• Last resort option

Dry-run mode (preview before auto-apply)¶

Every website/app (target) has a Dry-run toggle (Targets → edit a website/app). New websites/apps are created with Dry-run ON by default so a fresh workspace cannot accidentally auto-apply on day one.

• Dry-run ON: When the connector receives an approved fix, it parses the patch, runs path/safety checks, and reports back what it would apply — but it does not modify any files and does not restart your application. The error stays approved so you can review the simulation in the dashboard.
• Dry-run OFF: The connector applies the patch, takes its pre-apply backup, and runs post-apply health checks (with automatic rollback on failure as described above).

Use dry-run while you're getting comfortable with a connector or when wiring up a new website/app on a sensitive environment, then turn it off once you trust the pipeline. The setting is per website/app, so you can leave one website/app in dry-run while another auto-applies.

Where rollback backups live (and how long you can roll back)¶

Pre-apply rollback backups are taken by the connector, on your target server, immediately before each fix is applied. They are not uploaded to Patcherly and Patcherly does not retain or prune them.

• Location: Inside your project / connector backup folder on your own server (see your connector's "Backups" docs, e.g. PHP connector → Automatic Backup).
• Retention: Indefinite and customer-managed. The backups stay on disk until you delete them — there is no Patcherly-side cleanup job that removes them.
• Manual rollback: Available as long as the on-target backup files for that fix still exist. From the Errors page, click Rollback and the connector restores the affected files from its local backup.
• Manual rollback no longer possible if you (or anything else on your server, e.g. a deploy that wipes the connector's backup folder) have removed those backup files.

WordPress: rollback when the main plugin cannot load¶

On WordPress, Patcherly installs a small Rescue must-use plugin when you pair. If a fatal error prevents the normal connector from loading, Rescue can still:

• Pick up Rollback requests from the dashboard and restore files from the same on-target pre-apply backups under wp-content/uploads/patcherly/backups/
• Detect new log lines (including emergency.log and debug.log when configured)
• Apply approved fixes when the main plugin is unavailable

From Targets in the dashboard, use Run rescue now to trigger Rescue immediately. See WordPress connector → When your site won't load for wp-config setup and limits.

Rollback coordination: when the main Patcherly plugin is still running, its scheduled rollback job takes priority; Rescue only restores files when the main plugin is absent or has not polled recently. Patcherly uses a short-lived lock file so the two paths cannot restore the same error at once.

Rollback Safety¶

Rollback is safe because:

• Backups are created before every fix
• Backups are verified before application
• Atomic operations ensure consistency
• No data loss - only code changes are reverted

Rollback History¶

All rollbacks are tracked:

• When rollback occurred
• Why it was triggered
• What was restored
• Who initiated it (if manual)

View rollback history in the error details page.

Preventing Rollbacks¶

To reduce rollbacks:

• Review fixes carefully before approval
• Test in staging before production
• Monitor confidence scores – higher is better
• Keep your target URL correct – The basic health check (all plans) uses your target’s URL; if it’s wrong or the site is down for other reasons, rollback may trigger
• Restart when required – If Patcherly says restart is needed, do it so the basic health check sees a healthy app
• Use test suites (Agent Testing plan) – Extra validation before and after fixes

Rollback Best Practices¶

• Monitor after fixes: Watch for issues immediately after application
• Restart after rollback: If restart is required, restart your application promptly after rollback
• Review rollback reasons: Understand why rollback occurred
• Adjust thresholds: Tune health check thresholds if needed
• Request re-analysis: Get a new fix suggestion after rollback
• Verify rollback: After restart, verify the rollback restored the application correctly

Next Steps¶

• Learn about manual fixes
• Restart your application after fixes
• Understand error states
• Review approval workflow
• Audit Logs — Per-event record of Rollback Started, Rollback Done, and Rollback Failed events