Troubleshooting

Most plugin problems are quiet rather than loud: Fluxta skips something instead of throwing. This page maps a symptom onto its cause.

The plugin does not appear

Check the manifest first. Fluxta scans each plugin folder for a manifest.json and skips any folder without a valid one, silently — a folder that is not a plugin is not an error. A manifest missing a required field (name, apiVersion, version, title, description, actions) fails to load, as does one declaring an apiVersion other than 1, or a name that another installed plugin already uses.

Run the validator, which checks this and more:

fluxta validate

Then check that the build folder exists. fluxta restart links dist/<your-plugin-id>/. If the build never produced it — or produced it under a different name than the manifest's name — there is nothing to link.

Fluxta is not running

Fluxta writes a small descriptor file while it runs, and the CLI reads it to find the app. The message names the exact path it looked at.

• The app really is not running. Start it; the CLI never launches it.
• The app is running but the CLI still cannot see it. The descriptor may be stale from a previous session. Restart Fluxta.
• "the endpoint descriptor declares control protocol version …" — the CLI is older than the app. Update it with npm install -g @fluxta/cli.

The button does nothing

If nothing appears in the log either, the Action was never called. Three usual reasons:

1. The names do not match. The name on the Action class must be exactly the type of an entry in the manifest's actions. If they differ, Fluxta never sends the trigger. It reports no error; it skips a step it cannot route.
2. The Action is not declared at all. The manifest is the contract. An Action the code registers but the manifest does not declare is treated as one that does not exist.
3. The process is not running. Check the plugin's status in Fluxta. If it is Error or Stopped, read the log — the process most likely crashed on startup. Fluxta does not restart a crashed process.

The same rule covers everything else a plugin registers: a Value Source, an Options Source, or an Event Source whose key is absent from the manifest is never asked for anything.

The process exits immediately

Read dist/<your-plugin-id>/logs/<your-plugin-id>.log — the crash is almost always there.

The most common cause is a dependency that did not get bundled. Fluxta runs the entry file with its own Node runtime and does not install node_modules next to it, so an unbundled import fails at startup with a module-not-found error. The build must inline everything.

The second most common cause is calling connect() without handling its rejection. Authorization, version, and policy failures are final: the SDK does not retry them, and an unhandled rejection takes the process down.

The editor opens blank

Almost always absolute asset paths. The editor is served from a nested path, so a bundle referencing /assets/index.js asks for the wrong URL and loads nothing. With Vite, set base: "./".

Open the browser devtools for the iframe and look for 404s on the editor's own assets — that confirms it immediately.

If the assets load but the page still shows nothing, check that the editor was rebuilt. Editor rebuilds restart nothing, so a stale iframe keeps showing the old bundle until it is closed and reopened.

The editor throws

new ActionEditor() and new PluginEditor() work only inside the Fluxta editor iframe. They read a one-time grant that Fluxta injects into the page URL fragment, and they throw when it is missing.

An editor therefore cannot run standalone in a normal browser tab against a dev server — there is no grant there. Build it and let Fluxta mount it.

Changes are not picked up

• Background process changes apply on save; pnpm dev rebuilds and calls fluxta restart. If they did not, look at the dev output — a failed build never reaches the restart step, and a restart with Fluxta closed is skipped.
• Editor changes need the iframe reopened. Nothing restarts for an editor build.
• Manifest changes need fluxta restart, because the manifest is read when the plugin loads.

The wrong code is running

There is probably both an installed copy and a development link for the same plugin. The link wins while it is active — that is its purpose.

If the link's folder is missing or invalid, Fluxta reports the link as broken and refuses to fall back to the installed copy, so nothing runs at all. Either fix the build folder, or drop the link:

fluxta unlink

Unexpected settings

• Old shape. Stored settings can predate the current settings type. They are whatever was saved last, not what the TypeScript says today. Validate before using them.
• Only one save handler is live. onActionSave keeps a single handler. If it closes over React state, re-register it when that state changes, or read from a ref — otherwise it saves a stale value.
• The save handler failed. If it throws, or returns something that cannot be serialized, nothing is stored and the previously saved settings are kept. The dialog stays open and says the save failed; the error itself is logged in the editor iframe's console.
• A reference resolved to nothing. A {{plugin.action.key}} reference to a Run Variable that no earlier step produced resolves to an empty string rather than failing. If a setting arrives empty, check that the producing Action really runs before this one.