kestra-io/kestra · error · KestraRuntimeException

Failed to create %s '%s'. Error: %s

Error message

Failed to create %s '%s'. Error: %s

What it means

Thrown by AbstractPluginInterfaceFactory.resolve() when JacksonMapper.toMap() fails to deserialize the plugin configuration map into the plugin class — i.e., the configuration values do not map onto the plugin's fields (wrong types, unknown nested structure, JSON coercion failure). The original exception message is embedded. This is a KestraRuntimeException indicating the config block is structurally invalid for the target plugin type.

Source

Thrown at core/src/main/java/io/kestra/core/plugins/AbstractPluginInterfaceFactory.java:112

        Class<? extends Plugin> pluginClass = pluginRegistry
            .findClassByIdentifier(pluginVersion == null ? pluginType : pluginType + ":" + pluginVersion);
        if (pluginClass == null) {
            List<String> supportedVersions = pluginRegistry.getAllVersionsForType(pluginType);
            throw new KestraRuntimeException(
                "No %s can be found for '%s=%s', and version=%s. Supported versions are: %s".formatted(
                    lookupDisplayName(), typeProperty(), pluginId, pluginVersion, supportedVersions
                )
            );
        }

        // Plugins are handled as any serializable/deserialize plugins.
        T plugin;
        try {
            // Make sure config is not null, otherwise deserialization result will be null too.
            Map<String, Object> nonEmptyConfig = Optional.ofNullable(pluginConfiguration).orElse(Map.of());
            plugin = (T) JacksonMapper.toMap(nonEmptyConfig, pluginClass);
        } catch (Exception e) {
            throw new KestraRuntimeException(
                String.format("Failed to create %s '%s'. Error: %s", configDisplayName(), pluginId, e.getMessage())
            );
        }

        // Validate configuration.
        Set<ConstraintViolation<T>> violations;
        try {
            violations = validator.validate(plugin);
        } catch (ConstraintViolationException e) {
            throw new KestraRuntimeException(
                String.format("Failed to validate configuration for %s '%s'. Error: %s", configDisplayName(), pluginId, e.getMessage())
            );
        }
        if (!violations.isEmpty()) {
            ConstraintViolationException e = new ConstraintViolationException(violations);
            throw new KestraRuntimeException(
                String.format("Invalid configuration for %s '%s'. Error: '%s'", configDisplayName(), pluginId, e.getMessage()), e
            );

View on GitHub (pinned to 823fada927)

Solutions

  1. Read the embedded error message to find the failing field and type.
  2. Align the config value types with the plugin's current API for the installed version.
  3. Consult the plugin's documentation for the correct field types and names.
  4. Update the plugin version or revert the config to a known-good shape.

Example fix

# before
- id: upload
  type: io.kestra.plugin.aws.s3.Upload
  retry: "abc"   # expects int
# Failed to create ... Error: cannot deserialize

# after
- id: upload
  type: io.kestra.plugin.aws.s3.Upload
  retry: 3
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate config value types against the plugin class fields before resolution
Map<String,Object> cfg = Optional.ofNullable(pluginConfiguration).orElse(Map.of());
try {
    JacksonMapper.toMap(cfg, pluginClass);
} catch (Exception e) {
    log.warn("Config will fail to deserialize: {}", e.getMessage());
}

Try / catch

try {
    factory.resolve(identifier, config);
} catch (KestraRuntimeException e) {
    if (e.getMessage().startsWith("Failed to create")) {
        log.error("Plugin config deserialization error: {}", e.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: A config property expects an integer but receives a string that cannot be coerced; a nested object does not match the plugin's nested type; a required constructor argument is missing; a field type changed between plugin versions and the config is stale.

Common situations: Stale flow YAML after a plugin upgrade changed field types; typo in a nested config key; copy-paste of config from a different plugin.

Related errors

AI-assisted analysis of kestra-io/kestra@823fada927 (2026-08-14). Data as JSON: /api/errors/001727d42d213227. Report an issue: GitHub.