ory/kratos · error

An error occurred initializing cleanup

Error message

An error occurred initializing cleanup

What it means

This is a wrapped error from CleanupSQL: driver.NewWithoutInit failed while constructing the driver from the provided config options (e.g. invalid DSN format, unparsable config). The original error is preserved underneath this message, so inspect the wrapped cause for the real failure.

Solutions

1. Read the wrapped cause printed below this message — it names the actual problem.
2. Validate the DSN scheme is one of postgres, mysql, or cockroach.
3. URL-encode special characters in the DSN password (e.g. @ as %40).
4. Confirm the config file path passed via --config exists and parses as valid YAML/JSON.

Example fix

// before
DSN="postgres://user:p@ss@db:5432/kratos" kratos cleanup sql
// after
DSN="postgres://user:p%40ss@db:5432/kratos?sslmode=disable" kratos cleanup sql

// Validate the DSN scheme before running:
u, err := url.Parse(dsn)
if err != nil || (u.Scheme != "postgres" && u.Scheme != "mysql" && u.Scheme != "cockroach") {
    return fmt.Errorf("unsupported DSN scheme %q", u.Scheme)
}

if out, err := exec.Command("kratos", "cleanup", "sql").CombinedOutput(); err != nil {
    if strings.Contains(string(out), "An error occurred initializing cleanup") {
        log.Error("driver init failed; check wrapped cause and DSN", "out", string(out))
    }
}

When it happens

Trigger: Calling `kratos cleanup sql` when driver.NewWithoutInit returns a non-nil error — malformed DSN connection string, unsupported scheme (not postgres/mysql/cockroach), or invalid config options.

Common situations: DSN with wrong scheme (e.g. redis:// or sqlite paths in a version without SQLite support); password containing unescaped special characters; config file referenced by flags that cannot be read.

Related errors

• expected to get the DSN as an argument, or the…
• An error occurred while cleaning up expired data
• an error occurred initializing migrations
• required config value "dsn" was not set
• expected zero or two args, got

AI-assisted analysis of ory/kratos@b86338da04 (2026-09-07). Data as JSON: /api/errors/173560f0e5d05685. Report an issue: GitHub.

Appendix: source

Thrown at cmd/cleanup/handler.go:47

		configx.SkipValidation(),
	}

	if !flagx.MustGetBool(cmd, "read-from-env") {
		if len(args) != 1 {
			return errors.New(`expected to get the DSN as an argument, or the "read-from-env" flag`)
		}
		opts = append(opts, configx.WithValue(config.ViperKeyDSN, args[0]))
	}

	d, err := driver.NewWithoutInit(
		cmd.Context(),
		cmd.ErrOrStderr(),
		driver.WithConfigOptions(opts...),
	)
	if len(d.Config().DSN(cmd.Context())) == 0 {
		return errors.New(`required config value "dsn" was not set`)
	} else if err != nil {
		return errors.Wrap(err, "An error occurred initializing cleanup")
	}

	err = d.Init(cmd.Context(), &contextx.Default{})
	if err != nil {
		return errors.Wrap(err, "An error occurred initializing cleanup")
	}

	keepLast := flagx.MustGetDuration(cmd, "keep-last")

	err = d.Persister().CleanupDatabase(
		cmd.Context(),
		d.Config().DatabaseCleanupSleepTables(cmd.Context()),
		keepLast,
		d.Config().DatabaseCleanupBatchSize(cmd.Context()))
	if err != nil {
		return errors.Wrap(err, "An error occurred while cleaning up expired data")
	}

View on GitHub (pinned to b86338da04)