Troubleshooting¶

For current service status and incident history, see the Patcherly status page.

This guide helps you resolve common issues with Patcherly.

Dashboard sign-in problems¶

The dashboard at app.patcherly.com keeps you signed in with a regular session cookie — nothing is stored in your browser's local storage.

• If parts of the dashboard (billing, trial banner, metrics filters, onboarding checklist, in-app toasts, page tours, account-deletion status) seem stuck loading, refresh the page after signing in, or sign out and sign in again.
• If you use a strict privacy mode, make sure cookies are not blocked for app.patcherly.com.

Connector Issues¶

Applies to: all connectors (Node.js, Python, PHP, WordPress) on Linux, macOS, and Windows hosts. WordPress-specific guidance lives in Connectors → WordPress.

Connector Not Connecting¶

Symptoms: - Connector shows "Disconnected" status - Errors not being detected - Fixes not being applied

Solutions:

1. Verify OAuth credentials

2. Check that ~/.patcherly/credentials.json exists on the target server. If the file is missing or the access token has expired and refresh failed, re-pair from your installer's INSTALL_DIR — match the elevation you used the first time so credentials land in the same home:

   # macOS / Linux (defaults to /opt/patcherly-connector; add sudo if installer enabled systemd)
   /opt/patcherly-connector/start.sh login
   
   # Windows PowerShell (defaults to %USERPROFILE%\patcherly-connector)
   & "$env:USERPROFILE\patcherly-connector\start.ps1" login
   
   # Package installs
   patcherly login
   
   # PHP direct (manual install)
   php patcherly_agent.php login
   

3. Confirm the connector can reach Patcherly

4. In the dashboard, open your target and confirm status updates when the connector runs
5. The Patcherly API is hosted by us at https://api.patcherly.com. Connectors point at this host out of the box; you should not normally need to override it.

6. Docker / private networks: ensure outbound HTTPS to api.patcherly.com is allowed, and that containers can resolve DNS and reach the API (see connector logs for connection errors)

7. Review Connector Logs

8. Check logs/error.log (PHP/Python)
9. Check console output (Node.js)

10. Look for connection errors or authentication failures

11. Verify network and firewall

12. Production/Shared Hosting: Ensure firewall allows outbound HTTPS to api.patcherly.com
13. Docker / VPN: Confirm the connector’s environment can reach api.patcherly.com; fix DNS, routing, or proxy rules if logs show timeouts or TLS errors

“API server unavailable” during a Patcherly service outage¶

Applies to: all connectors (Node.js, Python, PHP, WordPress) on any OS.

Symptoms: - The connector or WordPress plugin reports API server unavailable (sometimes shown as a 503 error) - New errors on your site are not appearing in the dashboard - The website/app (target) may look connected in places but error reporting and fixes are paused

What this usually means:

Occasionally Patcherly runs service recovery after a major incident (restoring Patcherly's own service data — not your website files). While that work is in progress, connectors are intentionally paused so nothing is half-processed. This is temporary and expected.

What you should do:

1. Check the Patcherly status page for an active incident or maintenance notice.
2. If you are signed into the dashboard, you may be redirected to a maintenance page with a short “recovery in progress” message — that is normal; it does not mean your account was deleted.
3. Wait until the incident is resolved — you do not need to reinstall the connector or rotate your OAuth token.
4. After service is healthy again, refresh Targets in the dashboard; queued errors on the connector side resume sending automatically once the API accepts traffic again.
5. Your pre-apply backups (copies of files on your server before a fix) are not affected by service recovery.

When to keep troubleshooting:

If messages continue after the status page shows all systems operational for 15+ minutes, use the steps under Connector Not Connecting above — that points to a normal connectivity or credentials issue, not a service outage.

Connector Keeps Disconnecting¶

Symptoms: - Connector connects but disconnects frequently - Intermittent error detection

Solutions:

1. Verify OAuth credentials
2. Check that ~/.patcherly/credentials.json (or /root/.patcherly/credentials.json if paired with sudo) exists on the target server.
3. If it is missing or the token has expired, re-pair from your installer's INSTALL_DIR: start.sh login (Linux/macOS) / start.ps1 login (Windows) — or patcherly login for package installs.

4. Each pairing issues a new OAuth access token plus a fresh signing secret.

5. Check HMAC signing

6. HMAC secrets are per-token and bundled inside ~/.patcherly/credentials.json
7. HMAC verification is always mandatory for fix payloads (cannot be disabled)

8. If signature errors persist, re-pair to get a fresh token and secret

9. Review Rate Limits

10. Check if you're hitting rate limits (connector logs may mention throttling or “too many requests”)

11. Consider upgrading your plan if limits are too low

12. Check System Resources

13. Verify sufficient memory/CPU for connector
14. Check for process crashes or restarts
15. Review system logs for OOM (Out of Memory) errors

Account / Profile Updates¶

Applies to: the Patcherly dashboard at app.patcherly.com — browser-side only, no connector involved.

Email field won’t update in Profile¶

Why it happens: - Your sign-in email is fixed for security; it isn’t editable from Profile.

What to do: - Change password, name, or other fields without changing the email field. To use a different email, open Support from the bottom of the dashboard sidebar (Pro workspaces may include direct email there).

Error Detection Issues¶

Applies to: all connectors. Most steps below assume shell access on the host running the connector (Linux/macOS) — see the WordPress-specific path under Connectors → WordPress when commands aren't available.

Errors Not Being Detected¶

Symptoms: - Errors occur in application but don't appear in Patcherly - Connector is connected but no errors reported

Solutions:

1. Verify Log File Path
2. Check connector is monitoring correct log file
3. Verify log file exists and is readable

4. Check file permissions

5. Check Error Log Format

6. Connector looks for "ERROR" in log lines
7. Ensure your application logs errors with "ERROR" keyword

8. Check log format matches expected pattern

9. Test error reporting

10. Manually trigger an error in your application
11. Check if connector detects it

12. Review connector logs for error-reporting attempts

13. Check Queue Status

14. Review queue file for pending errors
15. Check for queue processing errors
16. Verify queue file is writable

Duplicate Errors¶

Symptoms: - Same error appears multiple times - Error count keeps increasing for same issue

Solutions:

1. This is Normal
2. Patcherly tracks how often the same error happens

3. The error detail shows occurrence count and last seen time

4. Ignore Repeated Errors

5. Use "Ignore" action to stop tracking specific errors
6. Errors are automatically deduplicated by normalized signature (log timestamps stripped); repeat hits bump occurrence count on the same row

Fix Application Issues¶

Applies to: all connectors. The fail-closed parsing behavior (unsupported_patch_format) below is identical across Node.js, Python, PHP, and WordPress.

Fixes Not Applying¶

Symptoms: - Fixes are approved but not applied - Connector shows "Pending" status for fixes - Error row ends Failed after an apply attempt (connector may report structured reason unsupported_patch_format)

Solutions:

1. Check that dry-run is off for the target. Targets in dry-run preview the change but never write files. Edit the target on the Targets page and turn off Dry-run when you're ready for the connector to apply fixes.
2. Verify file permissions
3. Make sure the connector's process can write to your application files.
4. Check directory permissions and file ownership.
5. Check the backup directory
6. The backup directory must exist and be writable by the connector.
7. On Python, Node, and PHP, this is controlled by the PATCHERLY_BACKUP_ROOT environment variable (default ../backups, outside your webroot).
8. Review connector logs
9. Look for parser errors, file-locking errors, or signature mismatches near the time of the failed apply.
10. If connector logs show fail-closed parse (unsupported_patch_format), see the next section.

Fix marked unsupported_patch_format (fail closed)¶

Symptoms: - Connector logs Patch parse failed (fail closed) or Failed to parse patch (fail closed) - Error status becomes Failed; the apply attempt is recorded with structured reason unsupported_patch_format (audit / connector report) - The target file on disk is unchanged (this is intentional)

Why: Patcherly connectors run a fail-closed apply pipeline. If the fix payload is not a valid unified diff (or arrives with corrupted hunk headers — for example because of CRLF line endings or a transport-layer rewrite), the connector refuses to apply anything, immediately rolls back the safety backup it took before parsing, and surfaces a structured failure to the API. No partial mutation can occur on this path. See Connectors → Fail-closed apply contract.

Solutions:

1. Re-request the analysis — ask Patcherly to regenerate the fix from the dashboard; the model will produce a fresh diff.
2. Check transport for CRLF/encoding issues — if you front the connector with a proxy or WAF that rewrites bodies, ensure it is not converting \n to \r\n inside the patch body.
3. Update the connector — older connector builds had a more permissive parser; upgrade to the latest connector version to pick up the fail-closed parsing behavior.
4. Don't manually retry the same fix — unsupported_patch_format is terminal for that fix attempt; nothing changes on retry until a new diff is generated.

Fixes Causing Errors¶

Symptoms: - Fix is applied but causes new errors - Application breaks after fix

Solutions:

1. Automatic Rollback
2. A basic health check runs for all plans after every fix (target URL must respond and not return 5xx). If it fails, Patcherly automatically rolls back (included on every plan).
3. On Agent Testing plans, enhanced health and test failures can also trigger automatic rollback.
4. Check rollback status in dashboard (Rolling back → Rolled back or Rollback failed)

5. Review rollback logs

6. Manual Rollback

7. Manual rollback is available to all users (every plan). Use "Rollback" in the dashboard on fixed/failed errors, choose a reason, and confirm.
8. Restore from backup manually if needed

9. See Rollback Guide

10. Review Fix Quality

11. Check confidence score (lower scores = higher risk)
12. Review fix code before approving
13. Test fixes in staging first

HMAC Verification Failures¶

Symptoms: - Fixes rejected with "HMAC verification failed" - Connector logs show signature errors

Solutions:

1. Re-pair the connector
2. The per-token HMAC secret lives in ~/.patcherly/credentials.json; re-pair from your installer's INSTALL_DIR to get a fresh token and secret:

   # macOS / Linux
   /opt/patcherly-connector/start.sh login
   
   # Windows PowerShell
   & "$env:USERPROFILE\patcherly-connector\start.ps1" login
   
   # Or for package installs
   patcherly login
   

3. WordPress: click Unpair then Pair connector in the plugin settings

4. Check Timestamp

5. HMAC includes timestamp (5-minute window)
6. Verify system clock is synchronized (NTP)
7. Check for timezone issues

Backup Issues¶

Applies to: Node.js, Python, and PHP connectors on Linux/macOS hosts (default backup root ../backups). For the WordPress plugin, backups live under wp-content/uploads/patcherly/backups/. Web-server hardening for both is in Connectors overview → Hardening backup folders and the public web.

Backups Not Created¶

Symptoms: - Fixes applied but no backups found - Backup directory is empty

Solutions:

1. Check Backup Directory

   # Verify directory exists
   ls -la ../backups
   
   # Check permissions
   chmod 755 ../backups
   

2. Verify Environment Variable

   echo $PATCHERLY_BACKUP_ROOT
   # Should point to backup directory
   

3. Check File Permissions

4. Ensure connector process can write to backup directory
5. Verify directory ownership

6. Check disk space

7. Review Backup Manager Logs

8. Check for backup creation errors
9. Verify backup manager is initialized
10. Review error messages

Backup Directory Accessible via Web¶

Symptoms: - Backups can be accessed via browser - Security risk

Solutions:

1. Move Outside Webroot
2. Set PATCHERLY_BACKUP_ROOT=../backups (parent directory)

3. Or use absolute path outside webroot

4. Protect the backup path — Prefer moving backups outside the webroot (PATCHERLY_BACKUP_ROOT). Connectors write .htaccess and IIS web.config inside the backup folder; those only help on Apache (AllowOverride All) or IIS — both are ignored on Nginx. For full coverage including ready-to-paste Nginx and Apache vhost snippets, see Connectors overview → Hardening backup folders and the public web. On WordPress, Site Health, Settings → Diagnostics, and an admin notice warn when a canary under uploads/patcherly returns HTTP 200 (optional PATCHERLY_BACKUP_ROOT moves backups only).

Performance Issues¶

Applies to: all connectors on any OS. Resource-usage symptoms most often show up on shared-hosting PHP/WordPress sites, but the diagnostic steps apply across the board.

Slow Error Detection¶

Symptoms: - Errors take long time to appear in dashboard - Delayed notifications

Solutions:

1. Check Polling Interval
2. Connectors poll every 5-30 seconds
3. Reduce interval for faster detection (increases load)

4. Check connector configuration

5. Review Queue Processing

6. Check queue size (large queues = slower processing)
7. Review queue processing frequency

8. Consider increasing processing rate

9. Check Network Latency

10. Slow or unstable networks delay the connector and dashboard updates
11. Try from a stable connection; if you use a VPN or strict firewall, ensure HTTPS to Patcherly isn’t blocked

High Resource Usage¶

Symptoms: - Connector using too much CPU/memory - System performance degraded

Solutions:

1. Review Connector Configuration
2. Reduce polling frequency
3. Limit queue size

4. Adjust log monitoring interval

5. Check for Memory Leaks

6. Monitor connector memory usage over time
7. Restart connector periodically if needed

8. Review connector code for leaks

9. Optimize Log Monitoring

10. Use log rotation
11. Limit log file size
12. Archive old logs

Authentication Issues¶

Applies to: all connectors on any OS. Pairing uses OAuth Device Authorization Grant; the ~/.patcherly/credentials.json location is the same on Linux, macOS, and Windows (under the home directory of the user that ran patcherly login).

Connector Authentication Failed¶

Symptoms: - "Authentication failed" errors - Connector shows as disconnected despite being installed

Solutions:

1. Verify OAuth credentials

2. Check that ~/.patcherly/credentials.json exists on the target server. If it is missing or you see an authentication error in the connector logs, re-pair from your installer's INSTALL_DIR:

   # macOS / Linux
   /opt/patcherly-connector/start.sh login
   
   # Windows PowerShell
   & "$env:USERPROFILE\patcherly-connector\start.ps1" login
   
   # Or for package installs / PHP direct
   patcherly login
   php patcherly_agent.php login
   

3. Re-pair the connector

4. On the target server, run start.sh login (Linux/macOS) or start.ps1 login (Windows) from your installer's INSTALL_DIR — or patcherly login (or patcherly logout && patcherly login) for package installs

5. WordPress: click Unpair then Pair connector in the plugin settings

6. Check Target Status

7. Verify the target is active in the dashboard
8. Ensure the Patcherly account used during pairing still has access

Session expired / signed out unexpectedly¶

Symptoms: - Dashboard shows Session expired or sends you back to login - Actions fail until you sign in again

Solutions:

1. Sign in again

2. Use Sign out (if shown), then sign back in with your email and password

3. Browser data

4. Clear cookies for app.patcherly.com and patcherly.com, or try a private/incognito window

5. Network or device change

6. After switching VPN, network, or device, sign out and sign in again

7. Signed out elsewhere

8. If you used Sign out on another tab or device, sign in again on this browser

Billing & subscriptions¶

Applies to: the Patcherly dashboard at app.patcherly.com — browser-side only, no connector involved.

I don’t see Billing or “Manage billing (Stripe portal)”¶

• The Billing tab on Profile is only shown when you are signed in as the workspace owner (invited team members have other profile tabs). If you expected to manage billing but do not see Billing, sign in with the owner account or open Support from the bottom of the dashboard sidebar.

I can’t switch plan in the Stripe portal¶

• Your Stripe Customer portal settings must allow plan switching and proration (configured in the Stripe Dashboard). If options are missing, open Support from the bottom of the dashboard sidebar.
• Always change plans via Profile → Billing → Manage billing (Stripe portal) for an existing workspace. The public Pricing page buttons point to new signup (/register?plan=...), not in-app upgrades for accounts you already have.

Payment failed or subscription stopped¶

• Open Profile → Billing → Manage billing (Stripe portal) and update your payment method.
• Check the email Stripe sent for a direct link. See Plans.

Downgrade blocked or limits after downgrade¶

• You may have more targets or usage than the new plan allows. Remove or disable extra targets, then try again. Limits and features are defined on the Pricing page.

Where are prices and plan features defined?¶

• Public list: patcherly.com/pricing. In app: Profile → Billing shows your current plan and what’s included. Overview: Plans.

Getting More Help¶

If you're still experiencing issues:

1. Check Documentation
2. Review relevant connector documentation
3. Check error management guides

4. Review FAQ

5. Collect Information

6. Connector logs
7. Error messages
8. System information

9. Steps to reproduce

10. Contact Support

11. Open Support from the bottom of the dashboard sidebar (FAQ — Support for plan-specific options)
12. Include collected information
13. Describe issue in detail