What causes "invalid %s %q: explicit port is required" in larksuite/cli?

Strip everything after host:port, including a trailing slash: `export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080`.

larksuite/cli · error

invalid %s %q: explicit port is required

Error message

invalid %s %q: explicit port is required

What it means

The proxy address must be a bare origin: scheme://127.0.0.1:port. Any URL path is rejected by proxyURL with the address shown redacted. A path has no meaning for an HTTP proxy endpoint and usually signals a copy-paste of a full website URL.

Source

Thrown at internal/transport/config.go:212

	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)
	}
	if u.Fragment != "" {
		return nil, fmt.Errorf("invalid %s %q: fragment is not allowed", envvars.CliProxyAddress, redacted)
	}
	return u, nil
}

// ApplyToTransport clones base and applies proxy plugin settings to the clone.
// Caller owns the returned *http.Transport.
func (c *Config) ApplyToTransport(base *http.Transport) (*http.Transport, error) {
	if base == nil {
		base = http.DefaultTransport.(*http.Transport)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Strip everything after host:port, including a trailing slash: `export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080`.
If you meant a web/UI URL for the proxy tool, find its plain proxy (CONNECT) listening port instead and use that.
Re-check the value: `echo $LARKSUITE_CLI_PROXY_ADDRESS` and remove any `/...` suffix.
Apply the same fix to LARKSUITE_CLI_PROXY_ADDRESS in ~/.lark-cli/proxy_config.json if set there.

Example fix

// before
export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080/proxy
// 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 */*) echo 'proxy address must not contain a path: use http://127.0.0.1:port only' >&2 ;; esac

Prevention

Use the proxy's CONNECT endpoint (bare host:port), not its web-admin URL.
Watch for trailing slashes from copy-paste.
Never append API routes or health-check paths to the proxy address.
Validate the final value with echo before committing it to scripts.

When it happens

Trigger: LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080/ or .../proxy or .../connect while proxy mode is enabled; ApplyToTransport fails at startup.

Common situations: Copying the proxy's web-admin URL (which has a path) instead of the proxy endpoint; a trailing slash from copy-paste; appending an API route to the proxy address.

Related errors

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