k3s-io/k3s · error

only https:// URLs are supported, invalid scheme:

Error message

only https:// URLs are supported, invalid scheme: 

What it means

Info.setServer parses the server URL supplied to clientaccess APIs and only accepts the https scheme, because the k3s supervisor/API endpoint is TLS-only. Any http:// (or other scheme) URL is rejected before CA bundle retrieval begins.

Source

Thrown at pkg/clientaccess/token.go:371

		return nil, err
	}
	p.Scheme = u.Scheme
	p.Host = u.Host
	client := GetHTTPClient(i.CACerts, i.CertFile, i.KeyFile, options...)
	return post(p.String(), body, client, i.Username, i.Password, i.Token(), options...)
}

// setServer sets the BaseURL and CACerts fields of the Info by connecting to the server
// and storing the CA bundle. If CACerts has already been set via ValidationOption,
// retrieval is skipped.
func (i *Info) setServer(server string) error {
	url, err := url.Parse(server)
	if err != nil {
		return errors.WithMessagef(err, "Invalid server url, failed to parse: %s", server)
	}

	if url.Scheme != "https" {
		return errors.New("only https:// URLs are supported, invalid scheme: " + server)
	}

	for strings.HasSuffix(url.Path, "/") {
		url.Path = url.Path[:len(url.Path)-1]
	}

	if len(i.CACerts) == 0 {
		cacerts, err := getCACerts(*url)
		if err != nil {
			return err
		}
		i.CACerts = cacerts
	}

	i.BaseURL = url.String()
	return nil
}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Use the https scheme: `--server https://10.0.0.10:6443`
2. If a proxy terminates TLS, point k3s at the https frontend or use TCP passthrough to the k3s port
3. In Go callers, scheme-check the URL before handing it to clientaccess

Example fix

# before
K3S_URL=http://10.0.0.10:6443 k3s agent

# after
K3S_URL=https://10.0.0.10:6443 k3s agent

u, err := url.Parse(serverURL)
if err != nil {
    return fmt.Errorf("unparseable server url: %w", err)
}
if u.Scheme != "https" {
    return fmt.Errorf("server url must use https, got %q", u.Scheme)
}
info, err := clientaccess.ParseAndValidateToken(u.String(), token)

func isHTTPSServerURL(raw string) bool {
    u, err := url.Parse(raw)
    return err == nil && u.Scheme == "https" && u.Host != ""
}

if err != nil && strings.Contains(err.Error(), "only https:// URLs are supported") {
    return fmt.Errorf("set K3S_URL/--server to https://; k3s does not serve plain http")
}

When it happens

Trigger: `k3s agent --server http://10.0.0.10:6443`, or Go code calling clientaccess.NewAccessInfo/ParseAndValidateToken with an http:// URL; also URLs missing their scheme entirely after parsing yield an empty scheme.

Common situations: Load balancers or reverse proxies terminating TLS in front of k3s with plain-http backends assumed; operators typing http out of habit; environment-provided URLs (K3S_URL) without a scheme.

Related errors

• token must not be empty
• invalid token CA hash length
• invalid token format
• ipv4 mode requested but no ipv4 network provided
• incorrect netMode for flannel tailscale backend

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/4519b35833ae3a80. Report an issue: GitHub.