What causes "invalid header %q: name cannot be empty" in sipeed/picoclaw?

Supply the header name before the separator: -H "X-API-Key: value"

invalid header %q: name cannot be empty

Error message

invalid header %q: name cannot be empty

What it means

Second guard of parseHeaderAssignments (helpers.go:248-252): a separator was present but the name side trimmed to empty — ': value' or '=value'. The parser refuses to create a header with no name, even though the value may itself be empty.

Source

Thrown at cmd/picoclaw/internal/mcp/helpers.go:251

func parseHeaderAssignments(values []string) (map[string]string, error) {
	if len(values) == 0 {
		return nil, nil
	}

	headers := make(map[string]string, len(values))
	for _, entry := range values {
		key, value, found := strings.Cut(entry, ":")
		if !found {
			key, value, found = strings.Cut(entry, "=")
		}
		if !found {
			return nil, fmt.Errorf("invalid header %q: expected 'Name: Value' or 'Name=Value'", entry)
		}
		key = strings.TrimSpace(key)
		value = strings.TrimSpace(value)
		if key == "" {
			return nil, fmt.Errorf("invalid header %q: name cannot be empty", entry)
		}
		headers[key] = value
	}

	return headers, nil
}

func looksLikeRemoteURL(target string) bool {
	parsedURL, err := url.ParseRequestURI(target)
	if err != nil {
		return false
	}
	if parsedURL.Host == "" {
		return false
	}
	switch strings.ToLower(parsedURL.Scheme) {
	case "http", "https":
		return true

View on GitHub (pinned to 49183d7e8d)

Solutions

Supply the header name before the separator: -H "X-API-Key: value"
Print the argument with printf '%s\n' "$H" | cat -A to spot the empty/whitespace name

Example fix

# before
picoclaw mcp add s https://api/x --transport http -H ": bearer"
# after
picoclaw mcp add s https://api/x --transport http -H "Authorization: bearer"

Defensive patterns

Strategy: validation

Validate before calling

validate_header() {
  local h=$1 name
  if [[ $h == *:* ]]; then name=${h%%:*}; else name=${h%%=*}; fi
  [[ -n "${name//[[:space:]]/}" ]] || { echo "header name empty in '$h'" >&2; return 1; }
}
validate_header "$h" && picoclaw mcp add "$name" "$url" --transport http -H "$h"

Prevention

Always include the header name before the separator
Validate templates/snippets that inject header values

When it happens

Trigger: `-H ": x"`, `-H "=x"`, or a whitespace-only name from a bad copy-paste where the real name landed before the opening quote.

Common situations: Retyping a header and dropping the name; snippet templates with a placeholder name left blank.

Related errors

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/61288d7db8c5249d. Report an issue: GitHub.