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.

Agent status on Sites¶

The colored dot next to the site name on Sites means:

Full table: Connector management → Agent status. Logout vs uninstall: Logout vs uninstall.

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 site 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 zip / Composer (CLI, not the agent poll loop)
   php patcherly_cli.php login
   

3. Confirm the connector can reach Patcherly

4. In the dashboard, open your site 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 site or app 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 Sites 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 site 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 (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, or returns to Analyzed with Stale patch

Solutions:

1. Check that Dry-run is off for the site. While Dry-run is on, the connector previews the change but never writes files. New sites start with Dry-run off; if you turned it on for a test, turn it off on the Sites page (table or expanded row under Auto Analysis / Auto Apply) when you want 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 .patcherly_backups under the agent working directory).
8. Review connector logs near the time of the failed apply, or see the next section when the dashboard shows Failed or Stale patch.

Fix could not be applied safely¶

Symptoms: - Error status becomes Failed, or returns to Analyzed with orange Stale patch - The site file on disk is unchanged (this is intentional) - No new backup folder was created for that attempt

Why: Before writing anything, the connector checks that the fix is usable and that the live files still match. If the fix is unreadable, or someone (or a deploy) changed the file after the draft was prepared, Patcherly leaves your site alone. See Connectors → When a fix cannot be applied safely.

Solutions:

1. For Stale patch - update or restore the live file as you prefer, then Mark as manually fixed or Delete the error (or run a fresh analysis on a new error if the issue returns).
2. For Failed after approve - run Analyze with AI again from Errors so a fresh draft is prepared.
3. Update the connector to the latest version if you are on an older build.
4. Don't keep retrying the same failed apply - nothing on disk changes until a new draft is ready or the live file matches again.

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 (site 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: on Patcherly → Home, click Re-Connect Account (or Disconnect, then Connect with Patcherly)

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 .patcherly_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

   # Default under the agent working directory
   ls -la .patcherly_backups
   
   # Check permissions
   chmod 755 .patcherly_backups
   

2. Verify Environment Variable

   echo $PATCHERLY_BACKUP_ROOT
   # Empty means the default `.patcherly_backups` is used
   

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 to a path outside the public document root

3. Or use an 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, Tools → Site Health and Settings → Diagnostics explain when a canary under uploads/patcherly returns HTTP 200 and how to add optional vhost hardening (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 site 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 CLI
   patcherly login
   php patcherly_cli.php login
   

3. Re-pair the connector

4. On the site 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: on Patcherly → Home, click Re-Connect Account (or Disconnect, then Connect with Patcherly)

6. Check Site Status

7. Verify the site 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 shown when you are the workspace owner of your active workspace, or when you do not own any workspace yet (so you can create one with a name, slug, and plan). Invited members who already own a workspace manage billing after switching to that workspace in the top bar. If you expected employer billing controls but only see create-your-own, that is expected - members cannot manage someone else’s subscription.

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 sites or usage than the new plan allows. Remove or disable extra sites, 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