invalid proxy address %q: use http:// — sidecar is same-host

Error message

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

What it means

ValidateProxyAddr rejects https:// proxy URLs. The sidecar is a same-host-only pattern: traffic goes over loopback or a virtual same-host bridge, so TLS adds no security, and cross-machine deployment (where TLS would matter) is explicitly out of scope.

Source

Thrown at sidecar/protocol.go:166

		}
		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)
	}
	// u.Hostname() strips the port and unwraps IPv6 brackets.
	if !isSameHost(u.Hostname()) {
		return errNotSameHost(addr)
	}
	return nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Change the scheme to http://: `export LARKSUITE_CLI_AUTH_PROXY="http://127.0.0.1:16384"`.
Connect the CLI directly to the sidecar's plaintext loopback listener (DefaultListenAddr 127.0.0.1:16384) instead of through a TLS-terminating reverse proxy.
If you were adding TLS because the sidecar seemed remotely reachable, restructure to the supported same-host deployment — TLS is intentionally not the mechanism here.
Keep any external-facing gateway separate; the CLI must point at the same-host http endpoint.

Example fix

// before
export LARKSUITE_CLI_AUTH_PROXY="https://127.0.0.1:16384"
// after
export LARKSUITE_CLI_AUTH_PROXY="http://127.0.0.1:16384"

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(addr)
if err == nil && u.Scheme == "https" {
	return errors.New("sidecar proxy must be http:// (same-host loopback); https:// is rejected")
}

Type guard

func isPlainHTTP(addr string) bool {
	u, err := url.Parse(addr)
	return err == nil && u.Scheme == "http"
}

Try / catch

if err := sidecar.ValidateProxyAddr(addr); err != nil {
	if strings.Contains(err.Error(), "use http://") {
		return fmt.Errorf("switch LARKSUITE_CLI_AUTH_PROXY to http:// — TLS is not needed same-host: %w", err)
	}
	return err
}

Prevention

Write http://, never https://, for the sidecar address.
Point the CLI at the sidecar's plaintext loopback listener directly, not a TLS reverse proxy.
If you think you need TLS, the deployment is cross-machine and unsupported — move the sidecar onto the sandbox host.
Document the http-only constraint in team config templates.

When it happens

Trigger: Setting LARKSUITE_CLI_AUTH_PROXY to an https URL such as "https://127.0.0.1:16384" or "https://localhost:16384" — typically when the sidecar was put behind TLS or the value was copied from an external proxy config.

Common situations: Configuring the sidecar the same way as a remote HTTPS proxy; a reverse proxy (nginx/caddy) exposing the sidecar over https; habitually writing https for all local services; docs from another product.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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