What causes "invalid %s %q: scheme must be http" in larksuite/cli?

Change the scheme to http: `export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080`.

invalid %s %q: scheme must be http

Error message

invalid %s %q: scheme must be http

What it means

The proxy-plugin mode only accepts an http:// proxy. proxyURL rejects https://, socks5://, or scheme-less addresses. The address is shown redacted (userinfo stripped) so credentials never appear in the error. This is intentional hardening: the fixed loopback proxy terminates plain HTTP CONNECT traffic locally.

Source

Thrown at internal/transport/config.go:201

	return false, fmt.Errorf("invalid %s %q (want true/false/1/0)", name, raw)
}

// proxyURL validates the fixed configured proxy configuration and returns its URL.
func (c *Config) proxyURL() (*url.URL, error) {
	raw := strings.TrimSpace(c.Proxy)
	if raw == "" {
		return nil, fmt.Errorf("%s is empty", envvars.CliProxyAddress)
	}
	redacted := redactProxyURL(raw)
	u, err := url.Parse(raw)
	if err != nil {
		// Do not wrap the raw url.Parse error: its string embeds the original
		// URL, which can contain userinfo (user:password). Return a redacted,
		// generic message instead.
		return nil, fmt.Errorf("invalid %s %q: malformed URL", envvars.CliProxyAddress, redacted)
	}
	if u.Scheme != "http" {
		return nil, fmt.Errorf("invalid %s %q: scheme must be http", envvars.CliProxyAddress, redacted)
	}
	if u.Host == "" {
		return nil, fmt.Errorf("invalid %s %q: missing host", envvars.CliProxyAddress, redacted)
	}
	// Security hardening: only allow a loopback proxy. This prevents accidental
	// cross-machine proxying of credentials/traffic.
	if u.Hostname() != "127.0.0.1" {
		return nil, fmt.Errorf("invalid %s %q: host must be 127.0.0.1", envvars.CliProxyAddress, redacted)
	}
	if u.Port() == "" {
		return nil, fmt.Errorf("invalid %s %q: explicit port is required", envvars.CliProxyAddress, redacted)
	}
	if u.Path != "" {
		return nil, fmt.Errorf("invalid %s %q: path is not allowed", envvars.CliProxyAddress, redacted)
	}
	if u.RawQuery != "" {
		return nil, fmt.Errorf("invalid %s %q: query is not allowed", envvars.CliProxyAddress, redacted)
	}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Change the scheme to http: `export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080`.
If your proxy is SOCKS-only, front it with a local HTTP proxy (e.g. a tool that maps HTTP CONNECT to your SOCKS upstream) and point the variable at that http:// loopback port.
Don't drop the scheme — a scheme-less value also fails; always write http://host:port.
Note https:// proxies are unsupported by design; TLS to the proxy is not how this plugin works — use the LARKSUITE_CLI_CA_PATH option only if your proxy does TLS interception of the upstream traffic, not for an https:// proxy address.

Example fix

// before
export LARKSUITE_CLI_PROXY_ADDRESS=socks5://127.0.0.1:1080
// after
export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080

Defensive patterns

Strategy: validation

Validate before calling

case "$LARKSUITE_CLI_PROXY_ADDRESS" in http://*) echo OK ;; *) echo 'LARKSUITE_CLI_PROXY_ADDRESS must start with http://' >&2 ;; esac

Prevention

Remember only http:// scheme is supported — never https:// or socks5://.
For a SOCKS/https upstream, front it with a local http:// loopback forwarder.
Don't strip the scheme to 'fix' the error; scheme-less values also fail.
Document the required format in your team's setup script.

When it happens

Trigger: LARKSUITE_CLI_PROXY_ADDRESS=http://… required, but user sets `https://127.0.0.1:8080`, `socks5://127.0.0.1:1080`, or `127.0.0.1:8080` (no scheme) while proxy mode is enabled.

Common situations: Copying a corporate proxy URL that is https; configuring a SOCKS proxy expecting support; omitting the scheme because curl-style env vars accept scheme-less values.

Related errors

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