What causes "invalid header %q: expected 'Name: Value' or 'Name=Value'" in sipeed/picoclaw?

Use 'Name: Value' form: -H "Authorization: Bearer "

invalid header %q: expected 'Name: Value' or 'Name=Value'

Error message

invalid header %q: expected 'Name: Value' or 'Name=Value'

What it means

parseHeaderAssignments (helpers.go:234-257) accepts either 'Name: Value' or 'Name=Value'; it tries ':' first, falls back to '=', and a -H/--header value containing neither separator is rejected with this message. Both forms are trimmed, so extra whitespace around the separator is fine.

Source

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

		env[key] = value
	}

	return env, nil
}

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 == "" {

View on GitHub (pinned to 49183d7e8d)

Solutions

Use 'Name: Value' form: -H "Authorization: Bearer <token>"
Quote the entire flag value in the shell so the colon/space survive intact

Example fix

# before
picoclaw mcp add s https://api/x --transport http -H X-API-Key
# after
picoclaw mcp add s https://api/x --transport http -H "X-API-Key: abc123"

Defensive patterns

Strategy: validation

Validate before calling

for h in "${HEADERS[@]}"; do
  case "$h" in
    *:*=*|*:*|*=*) ;;   # contains ':' or '='
    *) echo "invalid header '$h': expected 'Name: Value' or 'Name=Value'" >&2; exit 2 ;;
  esac
done

Prevention

Standardize on 'Name: Value' form for headers
Quote the whole -H argument so separators survive shell parsing

When it happens

Trigger: `-H X-API-Key` alone (no separator); quoting that consumed the colon; pasting only the header name when meaning to add it to a request template.

Common situations: Habit from tools where the header name alone toggles something; YAML/shell mangles ': ' inside unquoted values.

Related errors

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