Skip to content

Troubleshooting

Jump to bottom
Nick Hamze edited this page Aug 31, 2026 · 4 revisions

Troubleshooting

Fleet says the hub must use HTTPS

WordPress will only return an Application Password to a secure callback. Serve the hub over HTTPS and make sure Settings → General uses its HTTPS address.

Fleet cannot discover Application Passwords

Check the managed site:

  1. Open https://example.com/wp-json/ in a browser.
  2. Confirm it returns the WordPress REST API index rather than a login page, firewall challenge, or 404.
  3. Confirm the site uses HTTPS.
  4. Check whether a security plugin or host has disabled Application Passwords.
  5. Look for an Application Passwords section under Users → Profile.

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

Authorization succeeds, but Fleet cannot verify the credential

The most common cause is a server or proxy stripping the HTTP Authorization header before it reaches WordPress.

Check the managed site's web server, reverse proxy, CDN, and security plugin configuration. A valid Application Password must reach the WordPress REST API through HTTP Basic Authentication.

WordPress may already have created the credential even though verification failed. Look for Fleet for OpenStation on hub-domain under Users → Profile and revoke the unused entry before trying again.

Fleet connects, but reports a plugin-management error

The approving user must be allowed to manage plugins. On a normal WordPress install, use an administrator. On multisite, network-only operations may require a super administrator.

Reconnect the site while signed in as the correct user.

OpenStation will not install

Possible causes include:

  • The approving user cannot install or activate plugins.
  • WordPress cannot write to the plugins directory.
  • The server normally asks for FTP or SSH credentials during plugin installation.
  • WordPress.org is blocked from the managed server.
  • The managed site does not meet OpenStation's WordPress or PHP requirements.
  • A security policy blocks REST-based plugin installation.

Open the managed site's normal Plugins → Add New Plugin screen and try installing OpenStation there. The error shown by WordPress usually identifies the same underlying problem.

The stored credential cannot be read

The hub's WordPress authentication salt probably changed, or the stored value was damaged. Revoke the old Fleet Application Password on the managed site, remove the broken local connection after restoring access, and reconnect it.

Disconnect fails

Fleet removes a local connection only after the managed site confirms that its Application Password was revoked.

Make sure the managed site is online and its REST API is reachable, then try again. If the site is gone permanently, revoke or remove the credential directly from its database or restored dashboard before clearing Fleet's local metadata.

A private or local site will not connect

This preview intentionally uses WordPress's safe HTTP API and rejects loopback, private-network, and otherwise unsafe destinations. Do not disable that protection in production.

Public staging sites can be protected at the application level, but Fleet still needs access to the WordPress REST API and authorization screen.

Getting useful support

Open a GitHub issue with:

  • What you expected and what happened
  • Hub WordPress and PHP versions
  • Managed-site WordPress and PHP versions
  • The fixed Fleet notice and sanitized site error
  • Whether /wp-json/ works on the managed site
  • Whether ordinary plugin installation works there

Never include an Application Password, authorization header, callback URL, WordPress salt, or normal login password.

Clone this wiki locally