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

The Application Password callback and every authenticated API request require HTTPS. Serve the hub over HTTPS and make sure Settings → General uses its HTTPS address.

Fleet cannot find secure approval

Check the managed site:

  1. Open https://example.com/wp-json/ and confirm it returns the WordPress REST index.
  2. In the index's authentication object, confirm application-passwords has an authorization endpoint.
  3. Confirm Settings → General uses the site's public HTTPS address.
  4. Check for a firewall, login proxy, maintenance page, or security plugin intercepting the REST index or authorization screen.

Fleet also tries WordPress's plain-permalink REST form automatically.

Why is WordPress asking for a password?

Fleet is not asking for it. The browser has opened the managed site's own wp-admin. If you are not already signed in there, WordPress needs the normal login once before it can show its native connection approval screen. Fleet never receives that normal password.

After approval, WordPress generates a separate Application Password named Fleet for OpenStation on hub-domain. Subsequent Fleet requests use that credential without interactive logins.

Approval returns an error

Start a new connection rather than reloading an old authorization URL. Pending attempts expire after ten minutes and are consumed once. Confirm the hub remains signed in as the same user who started the attempt and that the callback still uses the hub's public HTTPS address.

If Fleet says it could not verify the credential, a server, proxy, CDN, or security plugin may be stripping the HTTP Authorization header. The credential may already exist even though verification failed; revoke the unused Fleet entry under Users → Profile → Application Passwords before retrying.

The setup progress screen stops

Keep the window open while WordPress downloads OpenStation. A first WordPress.org download can take a moment. If the screen reports an error or the browser lost its connection, return to Fleet. The site card remains connected and offers Finish OpenStation setup, so approval does not need to be repeated.

OpenStation will not install

Possible causes include:

  • the approving 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. Fleet can still manage API surfaces exposed by the connected WordPress site.

An API route returns 401 or 403

Authentication does not override route permissions. The approving WordPress account must have the capability required by that Core or plugin endpoint.

A 401 can also mean the Application Password was revoked on the managed site. Reconnect the site to create a new dedicated credential.

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.

Inbox looks stale or incomplete

Select Check now for an immediate refresh. Inbox items depend on the approving account being allowed to read the corresponding comments and content statuses. A site can remain connected while one collection returns a permission error; Fleet shows that error with the affected Inbox group.

Site Health checks are intentionally refreshed less often than connection and content checks. Use Check now when you need the latest result before acting.

Fleet search finds no results

Search terms must contain at least two characters. Fleet searches only routes and objects the approving WordPress account can read. Confirm the item is visible to that account and that the corresponding Core REST collection is advertised by the managed site.

A single search covers the first 25 matching connected sites. Choose a client to narrow a larger fleet. Fleet search does not index or copy site content onto the hub; it asks the connected sites live.

A client workspace is missing or opens the wrong group

Open each site's Agency view and give sites for the same customer the exact same client name. Workspaces are built from that hub-owned field. Sites without a client name appear together under Unassigned sites.

Disconnect fails

Fleet removes its local record only after the managed site confirms deletion of the exact Application Password. Make sure the site and REST API are reachable, then retry. You can revoke the named credential directly under Users → Profile → Application Passwords, but Fleet will 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 disposable Studio test environment uses development-only host handling 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 credentials, authorization headers, callback URLs, WordPress salts, or private domains.

Clone this wiki locally