What causes "invalid proxy address %q: %w" in larksuite/cli?

Use a clean canonical address: `export LARKSUITE_CLI_AUTH_PROXY="http://127.0.0.1:16384"`.

invalid proxy address %q: %w

Error message

invalid proxy address %q: %w

What it means

For a scheme-bearing LARKSUITE_CLI_AUTH_PROXY value, ValidateProxyAddr parses it with url.Parse; if parsing fails, the underlying url.Error is wrapped into this error. The string could not be interpreted as a URL at all.

Source

Thrown at sidecar/protocol.go:160

	// Bare host:port (no scheme) — validate as a net address.
	if !strings.Contains(addr, "://") {
		host, port, err := net.SplitHostPort(addr)
		if err != nil {
			return fmt.Errorf("invalid proxy address %q: expected host:port or http://host:port", addr)
		}
		if host == "" || port == "" {
			return fmt.Errorf("invalid proxy address %q: host and port must not be empty", addr)
		}
		if !isSameHost(host) {
			return errNotSameHost(addr)
		}
		return nil
	}

	u, err := url.Parse(addr)
	if err != nil {
		return fmt.Errorf("invalid proxy address %q: %w", addr, err)
	}
	if u.User != nil {
		return fmt.Errorf("invalid proxy address %q: userinfo is not allowed", addr)
	}
	if u.Scheme == "https" {
		return fmt.Errorf("invalid proxy address %q: use http:// — sidecar is "+
			"same-host only (loopback or virtual same-host bridge), so TLS adds "+
			"no security; cross-machine deployment is out of scope", addr)
	}
	if u.Scheme != "http" {
		return fmt.Errorf("invalid proxy address %q: scheme must be http", addr)
	}
	if u.Host == "" {
		return fmt.Errorf("invalid proxy address %q: missing host", addr)
	}
	if u.Path != "" && u.Path != "/" {
		return fmt.Errorf("invalid proxy address %q: path is not allowed", addr)
	}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Use a clean canonical address: `export LARKSUITE_CLI_AUTH_PROXY="http://127.0.0.1:16384"`.
For IPv6, balance the brackets: `http://[::1]:16384`.
Strip spaces/newlines/control characters (`echo "$LARKSUITE_CLI_AUTH_PROXY" | cat -A` to inspect).
If the value was templated, re-render the template and verify the substituted value.

Example fix

// before
export LARKSUITE_CLI_AUTH_PROXY="http://[::1:16384"
// after
export LARKSUITE_CLI_AUTH_PROXY="http://[::1]:16384"

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(addr) // for :// values
if err != nil {
	return fmt.Errorf("proxy URL %q unparseable: %w", addr, err)
}

Try / catch

var urlErr *url.Error
if err := sidecar.ValidateProxyAddr(addr); err != nil {
	if errors.As(err, &urlErr) || strings.Contains(err.Error(), "invalid proxy address") {
		return fmt.Errorf("fix LARKSUITE_CLI_AUTH_PROXY syntax (example: http://127.0.0.1:16384): %w", err)
	}
	return err
}

Prevention

Use the canonical form http://127.0.0.1:16384 — no exotic characters.
Balance IPv6 brackets exactly once.
Sanitize env values from templating/CI (strip spaces, newlines, control chars).
Validate at process startup with sidecar.ValidateProxyAddr.

When it happens

Trigger: Calling ValidateProxyAddr with a '://'-containing value that url.Parse rejects — e.g. "http://[::1:16384" (malformed IPv6 bracket), "http://host:port" where port is non-numeric (url.Parse tolerates many things but net checks elsewhere), control characters or spaces in the URL, "http://exa mple:16384".

Common situations: Unbalanced brackets around IPv6 addresses; spaces from copy/paste; newline or tab contamination in env values from config templates; stray characters like backslashes.

Related errors

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/c3bf6aa6c42d4768. Report an issue: GitHub.