larksuite/cli · error

invalid proxy address %q: host must be loopback (127.0.0.1 /

Error message

invalid proxy address %q: host must be loopback (127.0.0.1 / ::1) or a recognized same-host alias (localhost, host.docker.internal, host.containers.internal, host.lima.internal, gateway.docker.internal). The sidecar must run on the same physical machine as the sandbox — cross-machine deployment is not a sidecar and is not supported

What it means

errNotSameHost is returned by ValidateProxyAddr when the host in the LARKSUITE_CLI_AUTH_PROXY value is neither a loopback IP (127.0.0.1/::1) nor one of the recognized same-host aliases (localhost, host.docker.internal, host.containers.internal, host.lima.internal, gateway.docker.internal). The sidecar auth model requires the proxy to run on the same physical machine as the sandbox, so remote hosts are rejected by design.

Source

Thrown at sidecar/protocol.go:110

// isSameHost returns true when host is either a loopback IP or a recognized
// same-host DNS alias. Does not perform DNS resolution — a tampered /etc/hosts
// that points an alias elsewhere is out of scope (attacker with that access
// already has ambient control of the machine).
func isSameHost(host string) bool {
	if sameHostAliases[host] {
		return true
	}
	if ip := net.ParseIP(host); ip != nil {
		return ip.IsLoopback()
	}
	return false
}

// errNotSameHost is the shared error returned when the sidecar address does
// not resolve to the same physical host as the sandbox. Kept in one place so
// tests can look for a stable marker.
func errNotSameHost(addr string) error {
	return fmt.Errorf("invalid proxy address %q: host must be loopback "+
		"(127.0.0.1 / ::1) or a recognized same-host alias "+
		"(localhost, host.docker.internal, host.containers.internal, "+
		"host.lima.internal, gateway.docker.internal). "+
		"The sidecar must run on the same physical machine as the sandbox — "+
		"cross-machine deployment is not a sidecar and is not supported", addr)
}

// ValidateProxyAddr validates the LARKSUITE_CLI_AUTH_PROXY value.
// Accepted formats:
//   - http://host:port
//   - host:port         (bare address, treated as http)
//
// 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

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Run the sidecar on the same physical machine as the sandbox and point the config at 127.0.0.1:<port>, localhost:<port>, or [::1]:<port>.
2. From a container, use the runtime's host alias instead of a raw IP: host.docker.internal (Docker Desktop), host.containers.internal (Podman), host.lima.internal (Lima/colima/rancher-desktop), or gateway.docker.internal.
3. If the host is a Linux Docker daemon without host.docker.internal, add `--add-host=host.docker.internal:host-gateway` to the container run flags.
4. Do not attempt to host the proxy on a different machine — that deployment model is explicitly unsupported; use the documented sidecar pattern (same-host proxy listening on DefaultListenAddr 127.0.0.1:16384).

Example fix

// before (cross-machine, rejected)
export LARKSUITE_CLI_AUTH_PROXY="http://192.168.1.10:16384"
// after (same-host via alias)
export LARKSUITE_CLI_AUTH_PROXY="http://host.docker.internal:16384"

addr := os.Getenv("LARKSUITE_CLI_AUTH_PROXY")
if err := sidecar.ValidateProxyAddr(addr); err != nil {
	return fmt.Errorf("LARKSUITE_CLI_AUTH_PROXY unusable: %w", err)
}

func isSameHostAddr(addr string) bool {
	return sidecar.ValidateProxyAddr(addr) == nil
}

if err := sidecar.ValidateProxyAddr(addr); err != nil {
	if strings.Contains(err.Error(), "same physical machine") {
		return fmt.Errorf("sidecar must be same-host; use 127.0.0.1, localhost, or host.docker.internal: %w", err)
	}
	return err
}

When it happens

Trigger: Setting LARKSUITE_CLI_AUTH_PROXY (validated via ValidateProxyAddr, called by ResolveAccount / ResolveInterceptor / package init) to an address whose host resolves to a LAN IP, public IP, external hostname, or an unlisted container alias — e.g. http://192.168.1.10:16384 or http://my-proxy.example.com:16384.

Common situations: Running the sidecar in a separate Docker container/VM reachable only over the network; pointing the CLI at a teammate's or central shared proxy host; using the container's own IP instead of a host alias; typo like 127.0.0.2 (loopback-ish but not exactly loopback in this check it IS loopback — actually any 127.x passes IsLoopback, so this usually fires for 10.x/192.168.x/public hosts).

Related errors

• invalid proxy address %q: userinfo is not allowed
• invalid proxy address %q: use http:// — sidecar is same-host
• proxy address is empty
• invalid proxy address %q: expected host:port or http://host:
• invalid proxy address %q: host and port must not be empty

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