> For the complete documentation index, see [llms.txt](https://docs.valtimo.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valtimo.nl/configuration-guides/plugins/external-plugins/troubleshooting.md). # Troubleshooting External plugins depend on a service outside Valtimo, so most problems are connection or permission problems rather than configuration mistakes. This page starts from what you can see and points at the fix. Because Valtimo re-checks every integration on a fixed interval (one minute by default), a good first step for anything intermittent is simply to wait one cycle and refresh: an integration that was briefly unavailable recovers on its own, without any manual step. *** ## Find the symptom | What you see | Most likely cause | Where to go | | ------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | An integration shows **Unreachable** | Wrong base URL, a rotated secret, or the service is down | [Integration is unreachable](#integration-is-unreachable) | | A plugin shows **Review required** | Its package on the host changed and is no longer the accepted one | [Resolving it on a plugin host](/configuration-guides/plugins/external-plugins/plugin-status-and-reviews.md#resolving-it-on-a-plugin-host) | | An app shows **Review required** | The app changed its manifest under the same version | [Resolving it on an app](/configuration-guides/plugins/external-plugins/plugin-status-and-reviews.md#resolving-it-on-an-app) | | A plugin's actions fail although its integration is reachable | The integration no longer serves that plugin version | [No longer served](/configuration-guides/plugins/external-plugins/plugin-status-and-reviews.md#no-longer-served) | | A plugin shows **Awaiting host** | Declared by a deployment descriptor; its integration has not served it yet | [Plugin status and reviews](/configuration-guides/plugins/external-plugins/plugin-status-and-reviews.md#awaiting-host) | | A plugin shows **Incompatible** | The plugin declares a Valtimo version range this environment falls outside | [Plugin status and reviews](/configuration-guides/plugins/external-plugins/plugin-status-and-reviews.md#incompatible) | | A case tab, widget or page is blank or shows unavailable | The frontend origin is not allowed, or the plugin is suspended | [A plugin screen does not load](#a-plugin-screen-does-not-load) | | A process stops on a service task with a plugin error | The action failed, or the integration is unreachable | [An action fails in a process](#an-action-fails-in-a-process) | | The plugin's settings step shows a JSON text area | The plugin ships no configuration form | [The settings step asks for JSON](#the-settings-step-asks-for-json) | | A configuration cannot be deleted | Something still references it | [Manage an integration](/configuration-guides/plugins/external-plugins/manage-an-integration.md#deleting-configurations-and-integrations) | | An upload is refused | Invalid package, too large, or the version exists with different contents | [An upload is refused](#an-upload-is-refused) | | An app cannot be connected | Wrong details, the app is not ready, or its plugin is already registered | [An app cannot be connected](#an-app-cannot-be-connected) | | The plugin never reacts to events | No broker configured, the wrong events accepted, or the queue was reset | [Events do not reach the plugin](#events-do-not-reach-the-plugin) | | The plugin runs but does the wrong thing | A plugin-side problem | [Plugin logs](/configuration-guides/plugins/external-plugins/plugin-logs.md) | *** ## Integration is unreachable **Unreachable** means repeated check-ins failed. Configurations, process links and tabs stay in place and recover automatically once the integration answers again. Work through, in order: {% stepper %} {% step %} Confirm with the team operating the integration that the service is running {% endstep %} {% step %} Check the **Base URL** on the integration's row — open **Edit connection** to see it Valtimo must be able to reach that address. Between containers or networks, the address that works from your browser is often not the address that works from Valtimo. {% endstep %} {% step %} If the secret was rotated, set the new value under **Edit connection** Rotation is two-sided: the integration must be restarted with the matching token, and Valtimo must be given the same value. Until both sides agree, the status stays Unreachable. {% endstep %} {% endstepper %} {% hint style="info" %} Everything recovers on the first successful check-in after both sides match — there is nothing to re-activate and no configuration to rebuild. {% endhint %} *** ## A plugin screen does not load Plugin screens render inside a locked-down frame, and two things commonly stop them. **The frontend origin is not allowed.** Every URL users open the Valtimo frontend from must be listed under the integration's **Allowed frontend origins**, including reverse-proxy aliases. With no origins listed, no page can embed that integration's screens — see [Manage an integration](/configuration-guides/plugins/external-plugins/manage-an-integration.md#frontend-origins). After a change to origins or to the base URL, the page asks for a reload; the policy that permits embedding is applied when the page loads. **The plugin is suspended.** A plugin tagged **Review required** serves no screens at all until an administrator resolves it — see [Plugin status and reviews](/configuration-guides/plugins/external-plugins/plugin-status-and-reviews.md#review-required). If neither applies, check that the user is allowed to see the tab or widget at all: access to case tabs and widgets is governed by the standard access control rules — see [External plugins in cases and processes](/configuration-guides/plugins/external-plugins/external-plugins-in-cases-and-processes.md#access-control). *** ## An action fails in a process A failing plugin action surfaces as a process error on the service task, like any other failing action. The distinction that matters is whether the plugin ran: | Error | Meaning | Next step | | ------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | The integration is unreachable | The action never ran | [Integration is unreachable](#integration-is-unreachable) | | The plugin is awaiting review | The action was refused before running | [Review required](/configuration-guides/plugins/external-plugins/plugin-status-and-reviews.md#review-required) | | The plugin is no longer served by its integration | The action was refused before running | [No longer served](/configuration-guides/plugins/external-plugins/plugin-status-and-reviews.md#no-longer-served) | | An error from the plugin itself | The plugin ran and reported a failure | [Plugin logs](/configuration-guides/plugins/external-plugins/plugin-logs.md) | Retry the activity once the cause is resolved; nothing about the process link needs to be rebuilt. *** ## The settings step asks for JSON When a plugin ships its own configuration form, the **Enter data** step is that form. When it does not, Valtimo cannot invent one, so the step shows a **Properties (JSON)** text area instead and the settings have to be entered as JSON. Ask the plugin's supplier for the property names, types and an example — or, preferably, for a version that ships a configuration form. The same applies to an action's inputs in the process-link modeler. See [Configure a plugin](/configuration-guides/plugins/external-plugins/configure-a-plugin.md#plugins-without-a-settings-form). *** ## Events do not reach the plugin An action that works while an event handler stays silent points at event delivery, not at the plugin. Check, in order: {% stepper %} {% step %} Confirm the integration has an event broker **Edit connection** shows the **Event broker URL**. Empty means events are switched off for this integration entirely — no event ever arrives, whatever the plugin subscribed to. {% endstep %} {% step %} Confirm the event type was accepted for this configuration Only the events listed under **Events** on the configuration's permissions are delivered. A plugin that asks for an event the administrator did not accept never receives it. {% endstep %} {% step %} Check whether the queue was reset In **Live** mode, anything published while the integration was down is gone — expected, not a fault. Changing the queue mode or the inactivity TTL also starts a fresh queue and abandons what was waiting in the old one; so does exceeding the TTL in **Durable** mode. See [Event queue settings](/configuration-guides/plugins/external-plugins/manage-an-integration.md#event-queue-settings). {% endstep %} {% endstepper %} If all three check out, the event is reaching the integration and the plugin is not acting on it — a plugin-side problem, visible in [Plugin logs](/configuration-guides/plugins/external-plugins/plugin-logs.md). *** ## An upload is refused | Message | Cause | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | The plugin host rejected the upload | The package is invalid — a broken manifest, disallowed contents, or oversized files inside it | | Package too large | The package exceeds the accepted size (100 MB by default). The message names the package's size and the limit | | Already up to date | Not an error: this exact package is already installed, so there is nothing to overwrite | | This version exists with different contents | A version is never replaced silently. Review the requested permissions and confirm the overwrite | Package rules are the plugin developer's concern. For an invalid package, send the message to the plugin's supplier rather than trying to repackage it. See [Upload a plugin](/configuration-guides/plugins/external-plugins/upload-a-plugin.md). *** ## An app cannot be connected | Message | Cause and fix | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The app could not be connected | Wrong base URL or secret, or the app is not running. Correct the details and use **Retry** | | App added, but not ready yet | The app was saved but did not serve its plugin in time. Valtimo finishes the job automatically once the app is reachable; the configuration can be completed later from the Apps page | | App already registered | The plugin this app provides is already registered by another integration. Connect an app only once, or remove the existing registration first | | Refresh required | Expected. The page reloads so that the security policy for the new app's screens is applied |