Skip to content
Open Choice

Troubleshooting

Plugin is not available

Symptom: A run fails immediately with Plugin 'alias-name' is not available (not installed, not trusted, or disabled).

Causes and fixes:

  1. Plugin not installed — Open the Plugins panel and check whether the plugin appears. If not, install it from the Registry.

  2. Plugin disabled — In the Plugins panel, find the plugin and check its toggle. A disabled plugin is excluded from all runs.

  3. Plugin quarantined — A quarantined plugin is shown with a red status badge. See Plugin was auto-quarantined below.

  4. Alias does not match — The implied alias is the last dot-segment of the plugin ID. For com.open-choice.toy-calculator, the alias is toy-calculator. Check for typos. See Aliases.

Plugin was auto-quarantined

Symptom: A plugin shows quarantined status in the Plugins panel. Runs that reference it fail.

Cause: The plugin produced three errors within one hour, or its binary was not found at the recorded path after installation.

Fix:

  1. Open the plugin detail page and read the Runtime events log. The quarantine event will have a message explaining which condition triggered it.

  2. If the binary is missing (entrypoint not found), reinstall the plugin.

  3. If the quarantine was triggered by repeated errors, use Run self-test on the plugin detail page to check whether the plugin’s external dependencies (runtime, tool on PATH) are available.

  4. Once you have investigated, click Unquarantine on the plugin detail page.

If the plugin was quarantined because it appears on the revocation list, unquarantining will not persist — it will be re-quarantined the next time Open Choice starts. The correct fix is to wait for the publisher to release a new signed version.

Parse error in .oce file

Symptom: The run does not start; the editor shows a red marker on a specific line.

Common causes:

  • Single brackets instead of double — Task headers must use [[...]], not [...].
  • Using the plugin ID instead of an alias — Write [["toy-calculator::calculate"]], not [["com.open-choice.toy-calculator::calculate"]].
  • Invalid TOML — Missing quotes around a string value, mismatched array brackets, or a duplicate key.

Hover over the error marker in the editor to see the exact parse message.

Task runs but produces no output

Symptom: The run completes with success: true but the output directory is empty or does not exist.

Fix:

  1. Check the output_dir value in your .oce file. Relative paths are resolved relative to the .oce file’s location, not the current working directory.

  2. Expand the Finished event in the run panel. The artifacts list shows every file the plugin reported writing. If the list is empty, the plugin did not emit any ArtifactCreated events.

  3. If the directory was expected to be created but does not exist, verify that the plugin has write permission to the target path.

Help Explorer shows no documentation

Symptom: A plugin appears in the Help Explorer but has no endpoints or descriptions.

Cause: Help content is extracted and cached at install time. If the plugin did not respond to the api help command during installation, the cache will be empty.

Fix: Uninstall and reinstall the plugin. This re-runs the help extraction. If documentation is still missing after reinstallation, the plugin does not implement the help endpoint — contact the plugin publisher.

Verification failure (binary hash changed)

Symptom: After clicking Verify on the plugin detail page, the plugin is immediately quarantined.

Cause: The SHA-256 hash of the plugin binary no longer matches the value recorded at install time. The binary has been modified since installation.

Fix: If you modified the binary intentionally (e.g. you are developing the plugin), reinstall it through the normal install flow to record the new hash. If the modification was unexpected, do not unquarantine — delete the plugin binary and reinstall from the registry.

Run history is empty

Symptom: The History panel shows no entries even after completing runs.

Cause: Run history is stored in the application database. If the database was reset or the history was manually cleared, past entries are not recoverable.

Run history is populated by successful and failed run completions going forward. Skipped tasks do not appear in the history.

Application database location

The Open Choice SQLite database is stored at:

  • Windows: %APPDATA%\open-choice\open-choice.db
  • macOS: ~/Library/Application Support/open-choice/open-choice.db

If the application is in a broken state that no amount of plugin uninstall/reinstall can fix, you can delete this file. Open Choice will recreate it with an empty schema on next launch. This is equivalent to a factory reset.

Back up this file before deleting if you want to preserve your run history or aliases.

Reporting a bug

If you encounter a problem not covered here, file an issue at https://github.com/open-choice/app/issues with:

  • The runtime events log from the relevant plugin (copy from the plugin detail page)
  • The .oce file you were trying to run (remove any sensitive parameter values)