hasura/graphql-engine · error

source driver: unknown driver %v (forgotten import?)

Error message

source driver: unknown driver %v (forgotten import?)

What it means

Returned by source.Open when the URL scheme of the migration source doesn't match any registered source driver. Drivers register themselves in a registry (with driversMu) keyed by scheme (e.g. 'file', 'hasuradb', 'postgres'), and an unknown scheme means the driver package was never imported — a common trap with Go's init()-based driver registration.

Source

Thrown at cli/migrate/source/driver.go:131

	u, err := nurl.Parse(url)
	if err != nil {
		return nil, errors.E(op, err)
	}

	if u.Scheme == "" {
		return nil, errors.E(op, stderrors.New("source driver: invalid URL scheme"))
	}

	driversMu.RLock()

	d, ok := drivers[u.Scheme]

	driversMu.RUnlock()

	if !ok {
		return nil, errors.E(
			op,
			fmt.Errorf("source driver: unknown driver %v (forgotten import?)", u.Scheme),
		)
	}

	if logger == nil {
		logger = log.New()
	}

	driver, err := d.Open(url, logger)
	if err != nil {
		return driver, errors.E(op, err)
	}

	return driver, nil
}

// Register globally registers a driver.
func Register(name string, driver Driver) {
	driversMu.Lock()

View on GitHub (pinned to 724551b9ae)

Solutions

1. Add the missing driver import to the binary's entry point, usually as a blank import: `_ ".../cli/migrate/source/file"` and `_ ".../cli/migrate/database/hasuradb"`
2. Check the URL scheme passed to Open matches a registered driver exactly (file, hasuradb, postgres, ...)
3. If writing a custom driver, verify Register was called in its init() before Open

Example fix

// before
import "github.com/hasura/graphql-engine/cli/migrate/source"
src, err := source.Open(u, logger) // unknown driver "file"

// after
import (
  _ "github.com/hasura/graphql-engine/cli/migrate/source/file"
  _ "github.com/hasura/graphql-engine/cli/migrate/database/hasuradb"
  "github.com/hasura/graphql-engine/cli/migrate/source"
)
src, err := source.Open(u, logger)

u, err := nurl.Parse(srcURL)
if err != nil { return err }
switch u.Scheme {
case "file", "hasuradb", "postgres": // known schemes
	src, err := source.Open(u, logger)
	if err != nil { return err }
	_ = src
default:
	return fmt.Errorf("unsupported scheme %q", u.Scheme)
}

if _, err := source.Open(u, logger); err != nil {
    if strings.Contains(err.Error(), "unknown driver") {
        // add blank driver imports and rebuild
    }
    return err
}

When it happens

Trigger: Calling source.Open (directly or via migrate.NewMigrate/New) with a URL whose scheme has no registered driver, e.g. `foo://...`, or building a custom binary that imports cli/migrate but not cli/migrate/source/file or cli/migrate/database/hasuradb, so their init() registrations never run.

Common situations: Embedding the hasura CLI migrate API in your own Go program and forgetting the blank imports (`_ "github.com/hasura/graphql-engine/cli/migrate/source/file"`); typos in the source URL scheme; refactoring that drops a driver import.

Related errors

• operation failed: %w
• cannot write migration directory: %w
• applying migrations on source: %s: %w
• operation failed: %w
• error while deleting status for database '%s': %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/b93ef1fad7c37b0e. Report an issue: GitHub.