What causes "invalid %s %q: host must be 127.0.0.1" in larksuite/cli?

Append the port your proxy listens on: `export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080`.

invalid %s %q: host must be 127.0.0.1

Error message

invalid %s %q: host must be 127.0.0.1

What it means

The proxy address must carry an explicit port. proxyURL rejects loopback URLs without one (e.g. http://127.0.0.1). The fixed-proxy design needs a concrete endpoint to route all outbound traffic through, so a default-port guess is not allowed.

Source

Thrown at internal/transport/config.go:209

	}
	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)
	}
	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.

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Append the port your proxy listens on: `export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1:8080`.
Confirm the proxy's actual listening port (`ss -ltnp | grep <proxy>` or its config) and use it exactly.
If a variable supplies the port, ensure it isn't empty: `echo "[$PROXY_PORT]"`.
Fix the same value in ~/.lark-cli/proxy_config.json if you configure via file.

Example fix

// before
export LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1
// 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://127.0.0.1:[0-9]*) echo OK ;; *) echo 'proxy address needs an explicit port, e.g. http://127.0.0.1:8080' >&2 ;; esac

Prevention

Always include :<port>; there is no default-port fallback.
Look up the proxy's real listening port before configuring.
Watch for shell expansions that can drop an empty $PORT suffix.
Keep host and port as one literal string.

When it happens

Trigger: LARKSUITE_CLI_PROXY_ADDRESS=http://127.0.0.1 or http://127.0.0.1/ with proxy mode enabled; ApplyToTransport fails at startup with the redacted address.

Common situations: Assuming port 80/8080 defaults; truncating the port when copying a command; shell variable expansion dropping `:8080` because a var was empty.

Related errors

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