Troubleshooting
Start with the symptom Oruva reports, then check the corresponding contract.
| Symptom | Cause |
|---|---|
| "manifest id must match the plugin directory name" | Folder name and manifest id differ beyond letter case. Rename one to match the other. |
| "unsupported manifest field" | Typo, or a field from a newer API than this app version. |
| "unsupported schema_version" | Only 2 (and 1 for migrated legacy plugins) is accepted. New plugins must declare 2. |
| "uses asset placeholders but does not declare asset.read" | Add the permission the placeholder needs. |
"network permission must exactly match declared network destinations" (or the filesystem.write / process.launch equivalents) | permissions and capabilities disagree. Declare both sides, or neither. |
| "must be an exact HTTPS origin" / "must use a public DNS host" | A destination has a path, query, credentials, wildcard, IP literal, or local hostname. Use https://host only. |
| Plugin shows Incompatible | platforms or app-version range excludes this machine; fix compatibility. |
| Re-approval required after an edit | You changed an approval-hashed field — runtime, entry, permissions, capabilities, any action field including ui — or any file byte in the folder. Approve again. |
| Action missing from the right-click menu | The asset's media type is not in accepts, or the plugin is not enabled and approved. |
ui.html does not open; the action runs headless | The declared UI file is missing or mistyped. Oruva logs a warning and deliberately falls back to manifest args. An escaping path fails validation instead. |
| UI stays on “Waiting for the plugin interface” | The iframe did not post {type:'oruva-plugin:ready'} after installing its message listener. |
UI run immediately reports -1 | runId is invalid, another process is active, args is not flat, a key is outside the fixed whitelist, or asset-path is not in context. |
| Local preview fails | read-file was given a non-absolute or unannounced path, a non-image type, or an image over 32 MiB. |
Remote preview fails with network_destination_not_declared | The fetch-image URL's origin is not in capabilities.network.destinations. Declare it and re-approve. |
Remote preview fails with network_permission_denied or …_required | The user chose Deny, or the prompt was dismissed. Re-approval or Reset internet access returns the origin to ask. |
| Remote preview fails for another reason | fetch-image requires HTTPS raster content, rejects SVG or a non-HTTPS redirect, and caps the response at 8 MiB. |
open-url is refused | The site is not in capabilities.browser.origins, or process.launch with default_browser is not declared. |
| Files were written but the library did not refresh | Emit one file_written per absolute path before a same-run result with asset_path and status matched or success; replacements must keep the exact original name and extras must be siblings. |
| UI run stops after ten minutes | UI runs time out after 600 seconds. Split the work or make it resumable. Headless runs still time out after 30 seconds. |
| Works linked, fails installed | You depended on files outside the plugin folder or on a system Python; bundle every dependency you can and set runtime: "python" when appropriate. |
Store install reports plugin_signing_required | The catalog or package signature did not verify against the shipped trust store, or the trust store has no keys yet. Bundled plugins are unaffected. |
Install reports plugin_exists | A plugin with that id is already installed or linked. Use Update when a newer version is offered, or remove or unlink it first. |
Update reports plugin_up_to_date or plugin_linked | The offered version is not newer than the installed one, or the installed copy is a linked development folder that updates from its own files. |
| Catalog install reports a hash or package error | The package does not match its catalog SHA-256, exceeds 64 MiB compressed or 256 MiB extracted, has an unsafe archive layout, or fails manifest validation. |