What causes "bad gateway address: %w" in ipfs/kubo?

Fix the malformed URL in Migration.DownloadSources so it parses (e.g. "https://ipfs.io").

bad gateway address: %w

Error message

bad gateway address: %w

What it means

For custom DownloadSources entries in GetMigrationFetcher, each non-keyword value is parsed as a URL of a gateway/mirror. This error wraps a url.Parse failure for such an entry, meaning the configured source string is not a valid URL.

Source

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

	var fetchers []Fetcher
	for _, src := range downloadSources {
		src := strings.TrimSpace(src)
		switch src {
		case "HTTPS", "https", "HTTP", "http":
			// Expand the alias into the full ordered list of trustless
			// community-provided gateways so migration survives a
			// 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
	}

View on GitHub (pinned to 329838acdf)

Solutions

Fix the malformed URL in Migration.DownloadSources so it parses (e.g. "https://ipfs.io").
Validate each entry with url.Parse before writing it to config.
Use `ipfs config --json Migration.DownloadSources '[...]'` to write well-formed JSON values instead of manual edits.

Example fix

// before
"DownloadSources": ["https:/gateway.example.com"]
// after
"DownloadSources": ["https://gateway.example.com"]

Defensive patterns

Strategy: validation

Validate before calling

for _, src := range sources {
    if _, err := url.Parse(src); err != nil {
        return fmt.Errorf("bad DownloadSources entry %q: %w", src, err)
    }
}

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "bad gateway address") {
        // fix or drop the offending DownloadSources entry
    }
}

Prevention

Test each custom gateway URL with url.Parse before saving config
Write sources via `ipfs config --json` to avoid quoting errors
Trim spaces and quotes from pasted URLs

When it happens

Trigger: Migration.DownloadSources containing a custom gateway string that is not URL-parseable (spaces, stray characters, malformed like "http//host").

Common situations: Hand-editing DownloadSources JSON with a typo; pasting a URL with quotes or whitespace embedded; forgetting the "//" after the 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/3d1b8f93129b48bb. Report an issue: GitHub.