larksuite/cli · error

proxy address is empty

Error message

proxy address is empty

What it means

ValidateProxyAddr rejects an empty LARKSUITE_CLI_AUTH_PROXY value with 'proxy address is empty'. The sidecar proxy address was configured as an empty string, so there is no address to validate or connect to.

Source

Thrown at sidecar/protocol.go:140

//
// Host must be loopback or in sameHostAliases. The sidecar pattern is
// inherently same-machine; cross-machine deployment is a different product
// and is not supported by this feature.
//
// https:// is rejected because sidecar is a same-host pattern: loopback
// and virtual same-host bridges don't traverse any untrusted medium, so
// TLS adds no security. Cross-machine deployment is out of scope (see the
// host constraint above), so there is no scenario today where https
// provides a real benefit over http on loopback.
//
// userinfo (user:pass@) is rejected unconditionally — the sidecar protocol
// does not use basic auth, and the syntactic slot exists only as a phishing
// vector (e.g. http://127.0.0.1@attacker.com).
//
// Returns an error if the value is not a valid proxy address.
func ValidateProxyAddr(addr string) error {
	if addr == "" {
		return fmt.Errorf("proxy address is empty")
	}

	// 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)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Set the variable to a real address, e.g. `export LARKSUITE_CLI_AUTH_PROXY="127.0.0.1:16384"` or `http://127.0.0.1:16384` (DefaultListenAddr).
2. If you do not want the sidecar at all, unset the variable entirely (`unset LARKSUITE_CLI_AUTH_PROXY`) rather than setting it empty, so the proxy path is disabled instead of misconfigured.
3. Check your shell profile / dotenv / CI secret for a definition that sets it to the empty string.
4. Confirm the sidecar process is actually started and note its listen address, then use that address.

Example fix

# before
export LARKSUITE_CLI_AUTH_PROXY=
# after
export LARKSUITE_CLI_AUTH_PROXY="127.0.0.1:16384"
# or, to disable:
unset LARKSUITE_CLI_AUTH_PROXY

addr := os.Getenv("LARKSUITE_CLI_AUTH_PROXY")
if strings.TrimSpace(addr) == "" {
	return errors.New("LARKSUITE_CLI_AUTH_PROXY is empty; set it (e.g. 127.0.0.1:16384) or unset it to disable the sidecar")
}
if err := sidecar.ValidateProxyAddr(addr); err != nil {
	return err
}

func proxyAddrPresent() bool {
	return strings.TrimSpace(os.Getenv("LARKSUITE_CLI_AUTH_PROXY")) != ""
}

if err := sidecar.ValidateProxyAddr(addr); err != nil {
	if err.Error() == "proxy address is empty" {
		return fmt.Errorf("sidecar enabled but no address given; set LARKSUITE_CLI_AUTH_PROXY=http://127.0.0.1:16384 or unset it")
	}
	return err
}

When it happens

Trigger: ValidateProxyAddr("") is invoked from ResolveAccount, ResolveInterceptor, or package init when LARKSUITE_CLI_AUTH_PROXY is set but empty (e.g. `export LARKSUITE_CLI_AUTH_PROXY=` or an empty value in a config file/env template), where code treats 'set' as 'use proxy' but the value carries no address.

Common situations: Exporting the variable with no value in a shell profile; CI/CD secret configured as empty; config file with `auth_proxy = ""`; a templating step that substituted a missing variable with an empty string.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• invalid proxy address %q: host must be loopback (127.0.0.1 /
• invalid proxy address %q: expected host:port or http://host:
• invalid proxy address %q: host and port must not be empty
• invalid proxy address %q: %w
• invalid proxy address %q: userinfo is not allowed

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