temporalio/temporal · error

%w: unknown plugin %q, supported plugins: %v

Error message

%w: unknown plugin %q, supported plugins: %v

What it means

getPlugin looks up a SQL persistence plugin (mysql, postgres, sqlite, etc.) by name in the supportedPlugins registry. When the configured plugin name does not match any registered driver, it returns ErrPluginNotSupported wrapped with the requested name and the sorted list of valid plugin names. This fails fast at store construction rather than producing confusing driver errors later.

Source

Thrown at common/persistence/sql/store.go:79

	plugin, err := getPlugin(cfg.PluginName)
	if err != nil {
		return res, err
	}
	db, err := plugin.CreateDB(dbKind, cfg, r, logger, mh)
	if err != nil {
		return res, err
	}
	//revive:disable-next-line:unchecked-type-assertion
	res = db.(T)
	return res, err
}

func getPlugin(pluginName string) (sqlplugin.Plugin, error) {
	plugin, ok := supportedPlugins[pluginName]
	if !ok {
		keys := expmaps.Keys(supportedPlugins)
		slices.Sort(keys)
		return nil, fmt.Errorf(
			"%w: unknown plugin %q, supported plugins: %v",
			ErrPluginNotSupported,
			pluginName,
			keys,
		)
	}
	return plugin, nil
}

func GetPluginVisibilityQueryConverter(pluginName string) (sqlplugin.VisibilityQueryConverter, error) {
	plugin, err := getPlugin(pluginName)
	if err != nil {
		return nil, err
	}
	return plugin.GetVisibilityQueryConverter(), nil
}

View on GitHub (pinned to bde624efd1)

Solutions

1. Check the error message's supported plugins list and set persistence.sql.pluginName in config to one of those exact values (e.g. mysql8, postgres12, sqlite).
2. Verify the plugin driver is registered: ensure the corresponding sql plugin package is imported (blank import) in the binary being run.
3. Fix typos/case: plugin names are matched exactly via map lookup.
4. If using a custom driver, register it in supportedPlugins or use the driverName option appropriately.

Example fix

// before
config:
  persistence:
    sql:
      pluginName: psql
// after
config:
  persistence:
    sql:
      pluginName: postgres12

var supportedPlugins = map[string]sqlplugin.Plugin{"mysql8": ..., "postgres12": ..., "sqlite": ...}
if _, ok := supportedPlugins[cfg.PluginName]; !ok {
    return fmt.Errorf("plugin %q not supported", cfg.PluginName)
}

if _, err := persistence.GetPluginVisibilityQueryConverter(name); err != nil {
    if errors.Is(err, persistence.ErrPluginNotSupported) {
        logger.Fatal("bad persistence config", "error", err)
    }
    return err
}

When it happens

Trigger: Calling createDB or GetPluginVisibilityQueryConverter with a pluginName that is not a key of supportedPlugins, e.g. a config file specifying an unsupported DB type or a typo like 'psql' instead of 'postgres12'.

Common situations: Config mistakes (persistence sql plugin name misspelled), deploying a build that lacks a plugin registered via blank import, mixing up visibility-store plugin name with the main store plugin name, upgrading Temporal where plugin names changed.

Related errors

• %v rows were affected instead of 1
• corrupted history event batch, wrong version and IDs
• corrupted history event batch, empty events
• page size to read history tasks must be positive
• history task from queue has nil blob

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/bcdce2e708410c64. Report an issue: GitHub.