ory/hydra · error

NewRestore failed

Error message

NewRestore failed

What it means

After obtaining a restorer via NewRestore(srcPath), a failure creating the backup handle is wrapped as 'NewRestore failed'. This wraps the driver-level error from initiating the SQLite online backup against the source URI.

Source

Thrown at oryx/popx/migrator.go:108

	if err != nil {
		return errors.Wrap(err, "failed to acquire sql.Conn for restore")
	}
	defer func() { _ = conn.Close() }()

	return conn.Raw(func(driverConn any) error {
		if w, ok := driverConn.(interface{ Raw() driver.Conn }); ok {
			driverConn = w.Raw()
		}
		restorer, ok := driverConn.(interface {
			NewRestore(srcUri string) (*moderncsqlite.Backup, error)
		})
		if !ok {
			return errors.Errorf("driver %T does not support online restore", driverConn)
		}
		// See: https://sqlite.org/backup.html .
		backup, err := restorer.NewRestore(srcPath)
		if err != nil {
			return errors.Wrap(err, "NewRestore failed")
		}
		// Step(-1) copies all remaining pages in one call.
		for {
			more, stepErr := backup.Step(-1)
			if stepErr != nil {
				_ = backup.Finish()
				return errors.Wrap(stepErr, "backup.Step failed")
			}
			if !more {
				break
			}
		}
		return errors.Wrap(backup.Finish(), "backup.Finish failed")
	})
}

// UpTo runs up to step "up" migrations and applies them to the database.
// If step <= 0 all pending migrations are run.

View on GitHub (pinned to 4174065ffb)

Solutions

1. Verify srcPath points to an existing, readable SQLite database file
2. Check file permissions and that no other process exclusively locks the source
3. Read the wrapped cause error for the underlying open failure
4. Test opening srcPath directly with sqlite to confirm validity

Example fix

// before
restoreSQLiteOnline(ctx, db, "/data/backup.db") // file missing
// after
if _, err := os.Stat("/data/backup.db"); err != nil { return err }
err := restoreSQLiteOnline(ctx, db, "/data/backup.db")

// Verify the restore source before starting
info, err := os.Stat(srcPath)
if err != nil { return fmt.Errorf("restore source missing: %w", err) }
if info.Size() == 0 { return errors.New("restore source is empty") }

if err := restoreSQLiteOnline(ctx, db, srcPath); err != nil {
  var wrapped interface{ Unwrap() error }
  if errors.As(err, &wrapped) { log.Printf("restore cause: %v", errors.Unwrap(err)) }
  return err
}

When it happens

Trigger: The source database path is invalid, unreadable, not a SQLite file, or locked; the driver refuses to open the source for backup.

Common situations: Restoring from a file that was deleted/moved; wrong srcPath passed to the restore routine; source file permissions blocking read; source DB corrupted or in WAL state the driver can't attach.

Related errors

• driver %T does not support online restore
• backup.Step failed
• backup.Finish failed
• failed to acquire sql.Conn for restore
• The DSN connection string looks like a SQLite connection, bu

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/dbd8f729181f6cea. Report an issue: GitHub.