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
An integration shows Unreachable
Wrong base URL, a rotated secret, or the service is down
A plugin shows Review required
Its package on the host changed and is no longer the accepted one
An app shows Review required
The app changed its manifest under the same version
A plugin's actions fail although its integration is reachable
The integration no longer serves that plugin version
A plugin shows Awaiting host
Declared by a deployment descriptor; its integration has not served it yet
A plugin shows Incompatible
The plugin declares a Valtimo version range this environment falls outside
A case tab, widget or page is blank or shows unavailable
The frontend origin is not allowed, or the plugin is suspended
A process stops on a service task with a plugin error
The action failed, or the integration is unreachable
The plugin's settings step shows a JSON text area
The plugin ships no configuration form
An upload is refused
Invalid package, too large, or the version exists with different contents
An app cannot be connected
Wrong details, the app is not ready, or its plugin is already registered
The plugin never reacts to events
No broker configured, the wrong events accepted, or the queue was reset
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:
Confirm with the team operating the integration that the service is running
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.
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.
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. 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.
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.
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:
The plugin is no longer served by its integration
The action was refused before running
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.
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:
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.
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.
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.
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.
An upload is refused
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.
An app cannot be connected
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
Last updated