Skip to content

Troubleshooting

Jump to bottom
Nick Hamze edited this page Sep 1, 2026 · 4 revisions

Troubleshooting

Fleet says the hub must use HTTPS

OAuth redirects and the Application Password bootstrap both require a secure callback. Serve the hub over HTTPS and make sure Settings → General uses its HTTPS address.

Fleet cannot discover a secure connection

Check the managed site:

  1. Open https://example.com/wp-json/ and confirm it returns the WordPress REST index.
  2. If OpenStation is active, confirm the root's authentication object contains openstation-fleet-oauth.
  3. Open https://example.com/.well-known/oauth-authorization-server and confirm it returns JSON metadata.
  4. Check for a firewall, login proxy, maintenance page, or security plugin intercepting either URL.
  5. Confirm Settings → General uses the site's public HTTPS address.

Fleet also tries WordPress's plain-permalink REST form automatically. If OpenStation is not installed, Fleet falls back to Core Application Password discovery.

The OAuth approval returns to Fleet but does not connect

Fleet rejects the callback when state, issuer, code, callback URI, client id, or PKCE verification fails. Start a new connection instead of reloading an old approval URL; the authorization code is single-use and expires after five minutes.

Also confirm the hub can make a server-to-server HTTPS request to the managed site's token endpoint. A browser being able to reach the site does not prove that the hub server can.

Fleet connects, then later says the token is invalid

The access token should refresh automatically. Common reasons both tokens become unusable are:

  • the connection was revoked from the managed user's profile;
  • the approving user's password changed or the user was deleted;
  • the refresh token was idle for 30 days or reached its 90-day lifetime;
  • the hub's WordPress authentication salt changed, so its encrypted token cannot be opened; or
  • an old refresh token was replayed and OpenStation revoked the token family.

Disconnect any stale local entry if possible and create a new connection.

An API route returns 401 or 403

OAuth authentication does not override route permissions. The approving WordPress account must have the capability required by that Core or plugin endpoint. Reconnect while signed into the intended administrator account, or change that account's role on the managed site.

An API route returns “no route”

Open the managed site's REST index and confirm the namespace and route exist. A plugin may be inactive, may not expose that feature through REST, or may register a different route or method than expected. Fleet cannot remotely manage a feature with no API.

OpenStation will not install

Possible causes include:

  • the approving bootstrap user cannot install or activate plugins;
  • WordPress cannot write to the plugins directory;
  • the server requires interactive FTP or SSH credentials;
  • WordPress.org is blocked from the managed server;
  • the site does not meet OpenStation requirements; or
  • a security policy blocks REST-based plugin installation.

Try installing OpenStation through the managed site's normal Plugins → Add New Plugin screen. WordPress usually shows the same underlying error more directly.

Application Password authorization succeeds but Fleet cannot verify it

This applies only to the bootstrap path. A server, proxy, CDN, or security plugin may be stripping the HTTP Authorization header before it reaches WordPress. The credential may already exist even if Fleet verification failed; revoke the unused Fleet for OpenStation on hub-domain entry under Users → Profile before retrying.

Disconnect fails

Fleet removes the local connection only after the managed site confirms revocation. Make sure the site and REST API are reachable, then try again. You can revoke an OAuth connection directly under Users → Profile → Fleet connections on the managed site, but Fleet will still retain its local record until its disconnect request succeeds.

A private or local production site will not connect

Fleet intentionally keeps WordPress's safe HTTP boundary and rejects loopback and private-network targets. Do not disable that protection in production. The repository's local Studio test setup uses a disposable, development-only override that is never shipped.

Getting useful support

Open a GitHub issue with the expected result, actual result, both WordPress and PHP versions, HTTP status, fixed Fleet notice, and sanitized error. Never include tokens, passwords, authorization headers, callback URLs, WordPress salts, or private domains.

Clone this wiki locally