{"record":{"id":"173560f0e5d05685","repo":"ory/kratos","slug":"an-error-occurred-initializing-cleanup","errorCode":null,"errorMessage":"An error occurred initializing cleanup","messagePattern":"An error occurred initializing cleanup","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cleanup/handler.go","lineNumber":47,"sourceCode":"\t\tconfigx.SkipValidation(),\n\t}\n\n\tif !flagx.MustGetBool(cmd, \"read-from-env\") {\n\t\tif len(args) != 1 {\n\t\t\treturn errors.New(`expected to get the DSN as an argument, or the \"read-from-env\" flag`)\n\t\t}\n\t\topts = append(opts, configx.WithValue(config.ViperKeyDSN, args[0]))\n\t}\n\n\td, err := driver.NewWithoutInit(\n\t\tcmd.Context(),\n\t\tcmd.ErrOrStderr(),\n\t\tdriver.WithConfigOptions(opts...),\n\t)\n\tif len(d.Config().DSN(cmd.Context())) == 0 {\n\t\treturn errors.New(`required config value \"dsn\" was not set`)\n\t} else if err != nil {\n\t\treturn errors.Wrap(err, \"An error occurred initializing cleanup\")\n\t}\n\n\terr = d.Init(cmd.Context(), &contextx.Default{})\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"An error occurred initializing cleanup\")\n\t}\n\n\tkeepLast := flagx.MustGetDuration(cmd, \"keep-last\")\n\n\terr = d.Persister().CleanupDatabase(\n\t\tcmd.Context(),\n\t\td.Config().DatabaseCleanupSleepTables(cmd.Context()),\n\t\tkeepLast,\n\t\td.Config().DatabaseCleanupBatchSize(cmd.Context()))\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"An error occurred while cleaning up expired data\")\n\t}\n","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/ory/kratos/blob/b86338da04a040247a07f46100a86dcfb3875909/cmd/cleanup/handler.go#L29-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause printed below this message — it names the actual problem.","Validate the DSN scheme is one of postgres, mysql, or cockroach.","URL-encode special characters in the DSN password (e.g. @ as %40).","Confirm the config file path passed via --config exists and parses as valid YAML/JSON."],"exampleFix":"// before\nDSN=\"postgres://user:p@ss@db:5432/kratos\" kratos cleanup sql\n// after\nDSN=\"postgres://user:p%40ss@db:5432/kratos?sslmode=disable\" kratos cleanup sql","handlingStrategy":"try-catch","validationCode":"// Validate the DSN scheme before running:\nu, err := url.Parse(dsn)\nif err != nil || (u.Scheme != \"postgres\" && u.Scheme != \"mysql\" && u.Scheme != \"cockroach\") {\n    return fmt.Errorf(\"unsupported DSN scheme %q\", u.Scheme)\n}","typeGuard":null,"tryCatchPattern":"if out, err := exec.Command(\"kratos\", \"cleanup\", \"sql\").CombinedOutput(); err != nil {\n    if strings.Contains(string(out), \"An error occurred initializing cleanup\") {\n        log.Error(\"driver init failed; check wrapped cause and DSN\", \"out\", string(out))\n    }\n}","preventionTips":["URL-encode special characters in DSN passwords.","Use only supported schemes (postgres/mysql/cockroach).","Log full error chains — the message is only a wrapper around the real cause."],"tags":["database","initialization","driver","cli"],"backgroundTag":"module-init-failed","analyzedSha":"b86338da04a040247a07f46100a86dcfb3875909","analyzedAt":"2026-09-07T15:58:15.934Z","contentChangedAt":"2026-09-07T15:58:15.934Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}