Troubleshooting

How Updates Work

Understanding the update cycle helps diagnose issues:

1. WordPress checks for updates automatically (usually twice daily via WP-Cron, or when you visit Dashboard → Updates).
2. Troy Client intercepts each update check for Troy-enabled plugins.
3. Troy Client serves cached data if available.
4. Troy Client fetches fresh data from each Troy Server once the cache expires.
5. Available updates display on your normal WordPress updates screen.

The Cache

Troy Client caches API responses to reduce server load. The default cache lifetime is 10 minutes.

The cache also clears automatically after any plugin, theme, or WordPress update.

Adjusting the cache lifetime:

You can define a constant in wp-config.php to change the cache duration (in seconds). The minimum is 30 seconds:

define( 'Troy\Client\API_TIMEOUT', 120 ); // 2 minutes

Force a fresh check:

After the cache expires, visiting Dashboard → Updates triggers a new check. Note that the Check Again button only refreshes the WordPress core version check; it does not trigger a new API request to Troy Servers.

If you need an immediate refresh during development, you can delete the troy_client_api_request_cache site option from the database.

About the Cache Size

Troy Client limits its API cache to 333,000 bytes of serialized data. When the cache exceeds this limit, it gets purged and rebuilt from scratch.

How much fits depends on what's cached. The cache stores two kinds of responses:

• Update checks — lightweight version metadata (slug, version number, download URL, compatibility info). Each plugin takes roughly 500–800 bytes serialized, so the cache comfortably holds 400+ plugins worth of update data alone.
• Plugin details — the full response you see when you click "View details" on a plugin. This includes readme content, changelogs, contributor lists, and banners. A typical detail response runs 15–17KB serialized, limiting the cache to about 20 plugins with full details loaded.

In practice, update checks are cached first, and detail responses are only cached when you actively view a plugin's details. Most sites never hit the limit.

Updates Not Appearing

Checklist:

1. Is Troy Client active? Check your Plugins screen — Troy Client should be listed and active.
2. Does the plugin use Troy? Go to Tools → Site Health → Info and scroll to Troy Client — Dependent Plugins. The plugin should be listed there with its update repository URL.
3. Is your plugin outdated? The update only shows if the server has a newer version than what you have installed.
4. Has the API cache expired? Troy Client caches update responses for 10 minutes by default. Wait for it to expire, or install/update any plugin to trigger a cache reset.
5. Is the Troy Server reachable? Visit https://repo.example.org/ping in your browser (replace with the actual repository URL from Site Health). You should see a "status": "ok" response.

Connection Errors

Troy Client tests connectivity with every registered Troy Server and reports results in two places:

• Tools → Site Health → Status — shows a critical notice if any Troy Server is unreachable, listing the affected plugins and the specific error message.
• Tools → Site Health → Info → Troy Client — Communications — shows the reachability status for each repository URL, including the error details when a connection fails.

Check these first — the error message usually points to the cause.

Common causes:

1. The Troy Server is down or misconfigured. Copy the repository URL from Site Health and append /ping to it (e.g., https://repo.example.org/ping). Open that URL in your browser — a working server responds with "status": "ok".
2. External requests are blocked. If WP_HTTP_BLOCK_EXTERNAL is set to true in wp-config.php, WordPress blocks all outbound requests. Add the repository domains to WP_ACCESSIBLE_HOSTS (comma-separated) to allow Troy to connect (e.g., define( 'WP_ACCESSIBLE_HOSTS', 'repo.deploytroy.org,repo.example.org' )).
3. A security plugin is interfering. Some firewall plugins block outbound requests to unknown domains. Check your security plugin's firewall or allowlist settings and add the repository domain.

Updates Fail to Install

1. Check disk space at Site Health → Status — insufficient disk space shows up as a critical issue.
2. Verify that the plugins directory is writable at Site Health → Info → Filesystem Permissions.

Still Stuck?

• Manual fallback: download new plugin ZIP or installer from the developer, then upload it through Plugins → Add New → Upload Plugin.
• Contact the plugin developer — they can verify that the update is published and the server is responding.
• Ask for help in our Community Discord.