k3s-io/k3s · error

failed to parse config location %s: %w

Error message

failed to parse config location %s: %w

What it means

readConfigFileData parses the value passed via `--config` / K3S_CONFIG_FILE with url.Parse to decide between an http(s) fetch and a local file read. url.Parse fails on very few inputs - almost exclusively strings containing control characters (newline, NUL, etc.), since nearly anything else is syntactically parseable as a URL.

Source

Thrown at pkg/configfilearg/parser.go:336

	switch k := v.(type) {
	case string:
		return []any{k}
	case []any:
		return k
	default:
		str := strings.TrimSpace(ToString(v))
		if str == "" {
			return nil
		}
		return []any{str}
	}
}

// readConfigFileData returns the contents of a local or remote file
func readConfigFileData(file string) ([]byte, error) {
	u, err := url.Parse(file)
	if err != nil {
		return nil, fmt.Errorf("failed to parse config location %s: %w", file, err)
	}

	switch u.Scheme {
	case "http", "https":
		resp, err := http.Get(file)
		if err != nil {
			return nil, fmt.Errorf("failed to read http config %s: %w", file, err)
		}
		defer resp.Body.Close()
		return io.ReadAll(resp.Body)
	default:
		return os.ReadFile(file)
	}
}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Quote the path and strip whitespace: use an absolute path like --config /etc/rancher/k3s/config.yaml.
2. Check the variable for hidden characters: `printf '%s' "$K3S_CONFIG_FILE" | od -c` and remove any \n / \r / NUL bytes.
3. If the value comes from a script, assign it without command substitution newlines: K3S_CONFIG_FILE=$(head -1 path.txt | tr -d '\r\n').

Example fix

# before
K3S_CONFIG_FILE="$(cat /etc/k3s-config-path.txt)"  # includes trailing newline -> url.Parse fails
k3s server --config "$K3S_CONFIG_FILE"

# after
K3S_CONFIG_FILE="$(tr -d '\r\n' < /etc/k3s-config-path.txt)"
k3s server --config "$K3S_CONFIG_FILE"

// Reject config locations containing control characters before launching k3s:
func validConfigLocation(s string) bool {
    if strings.TrimSpace(s) == "" {
        return false
    }
    for _, r := range s {
        if r < 0x20 || r == 0x7f {
            return false
        }
    }
    _, err := url.Parse(s)
    return err == nil
}

When it happens

Trigger: Passing a config location containing control characters or otherwise unparsable URL syntax to --config (pkg/configfilearg/parser.go:334-337), e.g. a shell/env variable with an embedded newline or CR.

Common situations: Config path read from an env var or file with a trailing newline/CR not stripped; copy-paste from Windows docs introducing CR characters; script-generated paths using unquoted command substitution.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• --server is required
• insufficient PSK bytes
• Flannel configuration not defined
• Initial server URL host is not defined for load balancer
• embedded registry mirror requires embedded containerd

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