ory/kratos · error

an error occurred initializing migrations

Error message

an error occurred initializing migrations

What it means

getPersister builds the storage driver and calls d.Init with driver.SkipNetworkInit to prepare migrations. If driver initialization fails — typically because the database is unreachable, credentials are wrong, or the dialect is unsupported — the error is wrapped with this message. It is a generic wrapper around a deeper driver/database error.

Solutions

1. Read the wrapped cause below this message — it names the actual driver failure.
2. Verify the DSN (driver name, host, port, user, password, database) is correct.
3. Confirm the database is running and reachable from where the command runs (ping/psql/mysql test).
4. Ensure the database flavor is supported by the driver used in this build.

Example fix

// before
export DSN=postgres://wrong:pass@localhost:5432/kratos?sslmode=disable
kratos migrate sql up
// after
export DSN=postgres://kratos:secret@localhost:5432/kratos?sslmode=disable
kratos migrate sql up

// before running migrations
conn, err := pgx.Connect(ctx, dsn)
if err != nil { log.Fatalf("database unreachable: %v", err) }
conn.Close(ctx)

null

if err := runMigrations(ctx, dsn); err != nil {
    if strings.Contains(err.Error(), "initializing migrations") {
        // inspect wrapped cause: connection/auth/dialect
        time.Sleep(5 * time.Second)
        return runMigrations(ctx, dsn) // retry once after infra check
    }
    return err
}

When it happens

Trigger: Running any `migrate` subcommand (e.g. `migrate sql up`) when driver.Init fails: bad DSN, database down, missing driver support, or connection refused during initialization.

Common situations: Wrong DSN in env/config, database container not started yet, network/firewall blocking the DB, unsupported database flavor, or invalid credentials in CI pipelines.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• expected to get the DSN as an argument, or the…
• An error occurred initializing cleanup
• An error occurred while cleaning up expired data
• migrations have not yet been fully applied
• required config value "dsn" was not set

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

Appendix: source

Thrown at cmd/migrate/handler.go:73

			fmt.Println(cmd.UsageString())
			return nil, cmdx.FailSilently(cmd)
		}
		d, err = driver.NewWithoutInit(
			cmd.Context(),
			cmd.ErrOrStderr(),
			driver.WithConfigOptions(
				configx.WithFlags(cmd.Flags()),
				configx.SkipValidation(),
				configx.WithValue(config.ViperKeyDSN, args[0]),
			))
		if err != nil {
			return nil, err
		}
	}

	err = d.Init(cmd.Context(), &contextx.Default{}, append(opts, driver.SkipNetworkInit)...)
	if err != nil {
		return nil, errors.Wrap(err, "an error occurred initializing migrations")
	}

	if err := popx.VerifyDialect(cmd.Context(), d.Persister().GetConnection(cmd.Context())); err != nil {
		return nil, err
	}

	return d, nil
}

func (h *MigrateHandler) MigrateSQLDown(cmd *cobra.Command, args []string, opts ...driver.RegistryOption) error {
	p, err := h.getPersister(cmd, args, opts)
	if err != nil {
		return err
	}
	return popx.MigrateSQLDown(cmd, p.Persister())
}

func (h *MigrateHandler) MigrateSQLStatus(cmd *cobra.Command, args []string, opts ...driver.RegistryOption) error {

View on GitHub (pinned to b86338da04)