golang-migrate/migrate · error

no scheme

Error message

no scheme

What it means

internal/url's SchemeFromURL returns errNoScheme ('no scheme') when the connection-string URL has no scheme, i.e. there is no ':' with at least one character before it. The migrate CLI uses this function to map a database URL to its registered driver package, so a scheme-less URL cannot be routed to any driver.

Source

Thrown at internal/url/url.go:8

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

1. Prefix the URL with its driver scheme, e.g. postgres://user:pass@host/db, mysql://..., or file:// for -source.
2. Verify the DATABASE_URL / flag value actually contains the scheme (echo it before use).
3. Quote the URL in shell scripts so special characters aren't consumed.
4. Update golang-migrate if you use a valid driver scheme that your older version doesn't support.

Example fix

// before
migrate -path ./migrations -database "mydb.example.com:5432/app" up
// after
migrate -path ./migrations -database "postgres://user:pass@mydb.example.com:5432/app?sslmode=disable" up

func requireScheme(u string) error {
	if i := strings.Index(u, ":"); i < 1 {
		return errors.New("URL must include a driver scheme, e.g. postgres://...")
	}
	return nil
}
// check before: requireScheme(databaseURL)

When it happens

Trigger: Calling migrate against a URL like 'localhost:5432/db'? No — precisely strings with no ':' before index 1, e.g. 'hello', or URLs passed via -database/-source that lack the 'driver://' prefix; SchemeFromURL('hello') returns errNoScheme.

Common situations: Forgetting the 'postgres://' or 'mysql://' prefix in -database/-source flags; env variables like DATABASE_URL missing the scheme; shell quoting stripping parts of the URL; new driver URLs the migrate version doesn't know how to parse.

Related errors

• no config
• no database name
• max retries exceeded
• digits must be positive
• the seq and format options are mutually exclusive

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