bad gateway address: url scheme must be http or https

Error message

bad gateway address: url scheme must be http or https

What it means

Custom DownloadSources gateway URLs must use the http or https scheme (a missing scheme defaults to https). This error is returned when a parsed entry has some other scheme such as ftp, file, or ipfs.

Source

Thrown at repo/fsrepo/migrations/migrations.go:194

			// single-gateway outage.
			for _, gw := range defaultMigrationGateways {
				fetchers = append(fetchers, NewHttpFetcher(distPath, gw, httpUserAgent, 0))
			}
		case "IPFS", "ipfs":
			return nil, errors.New("IPFS downloads are not supported for legacy migrations (repo versions <16). Please use only HTTPS in Migration.DownloadSources")
		case "":
			// Ignore empty string
		default:
			u, err := url.Parse(src)
			if err != nil {
				return nil, fmt.Errorf("bad gateway address: %w", err)
			}
			switch u.Scheme {
			case "":
				u.Scheme = "https"
			case "https", "http":
			default:
				return nil, errors.New("bad gateway address: url scheme must be http or https")
			}
			fetchers = append(fetchers, NewHttpFetcher(distPath, u.String(), httpUserAgent, 0))
		}
	}

	switch len(fetchers) {
	case 0:
		return nil, errors.New("no sources specified")
	case 1:
		return fetchers[0], nil
	}

	// Wrap fetchers in a MultiFetcher to try them in order
	return NewMultiFetcher(fetchers...), nil
}

func migrationName(from, to int) string {
	return fmt.Sprintf("fs-repo-%d-to-%d", from, to)

View on GitHub (pinned to 329838acdf)

Solutions

Change the source to an https:// (or http://) URL.
Omit the scheme entirely if https is acceptable — a bare host defaults to https.
Remove invalid entries and rely on the default migration gateways.

Example fix

// before
"DownloadSources": ["ftp://mirror.example.com/dist"]
// after
"DownloadSources": ["https://mirror.example.com/dist"]

Defensive patterns

Strategy: validation

Validate before calling

u, _ := url.Parse(src)
if u.Scheme != "" && u.Scheme != "http" && u.Scheme != "https" {
    return fmt.Errorf("source %q must use http/https", src)
}

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "scheme must be http or https") {
        // rewrite the entry with an https:// prefix
    }
}

Prevention

Use only https:// URLs for custom download sources
Omit the scheme to accept the https default
Never point migrations at ftp/file/ipfs URLs

When it happens

Trigger: Migration.DownloadSources containing an entry like "ftp://mirror.example.com" or "file:///path"; also triggered when the entry parses but has a non-HTTP scheme.

Common situations: Pointing migrations at an internal mirror over an unsupported protocol; copying a distribution URL from a non-HTTP source; typos producing an unexpected scheme.

Understand the failure class

HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/a4982c3ef584f5b8. Report an issue: GitHub.