What causes "URL cannot be empty" in golang-migrate/migrate?

Set the URL before calling: pass a non-empty connection string like "postgres://user:pass@host:5432/db" to migrate.New or the driver's Open.

golang-migrate/migrate · error

URL cannot be empty

Error message

URL cannot be empty

What it means

SchemeFromURL (internal/url/url.go) parses a scheme out of a migration URL string. If the URL is the empty string, there is nothing to parse, so it returns errEmptyURL ("URL cannot be empty") immediately instead of attempting scheme extraction. This guards the driver-lookup path in database/source Open functions which need a scheme to select a driver.

Source

Thrown at internal/url/url.go:9

package url

import (
	"errors"
	"strings"
)

var errNoScheme = errors.New("no scheme")
var errEmptyURL = errors.New("URL cannot be empty")

// schemeFromURL returns the scheme from a URL string
func SchemeFromURL(url string) (string, error) {
	if url == "" {
		return "", errEmptyURL
	}

	i := strings.Index(url, ":")

	// No : or : is the first character.
	if i < 1 {
		return "", errNoScheme
	}

	return url[0:i], nil
}

View on GitHub (pinned to 01a9643f14)

Solutions

Set the URL before calling: pass a non-empty connection string like "postgres://user:pass@host:5432/db" to migrate.New or the driver's Open.
Validate the env var / config field is non-empty before invoking the library (os.Getenv check).
If reading from config files, check for empty string after loading and fail early with your own clearer message.

Example fix

// before
m, err := migrate.New(os.Getenv("MIGRATION_URL"), "file://migrations")
// after
url := os.Getenv("MIGRATION_URL")
if url == "" {
    log.Fatal("MIGRATION_URL environment variable is not set")
}
m, err := migrate.New(url, "file://migrations")

Defensive patterns

Strategy: validation

Validate before calling

if u == "" {
    return fmt.Errorf("migration URL is required")
}
_, err := iurl.SchemeFromURL(u) // or just ensure non-empty before migrate.New

Try / catch

if _, err := migrate.New(url, sourcePath); err != nil {
    if err.Error() == "URL cannot be empty" { /* handle empty config */ }
}

Prevention

Check os.Getenv("DATABASE_URL") != "" at startup and fail fast with a clear message.
Validate all connection strings during config loading, before any library calls.
Default empty URLs to a documented local development DSN in dev environments.

When it happens

Trigger: Calling SchemeFromURL("") directly, or calling a database/source driver Open (e.g. database.Open, source.Open) with an empty URL string (e.g. migrate.New("", path), or a DSN sourced from an unset environment variable).

Common situations: DATABASE_URL or similar env var is empty/unset; config struct field left at zero value; template rendering produced an empty connection string; passing "" for the URL argument of migrate.New/migrate.NewWithDatabaseInstance plumbing.

Related errors

AI-assisted analysis of golang-migrate/migrate@01a9643f14 (2026-09-02). Data as JSON: /api/errors/b5a19aac9703be8b. Report an issue: GitHub.