larksuite/cli · error

invalid URL

Error message

invalid URL

What it means

ValidateDownloadSourceURL parses the caller-supplied download URL; if url.Parse fails or yields a nil URL, it throws "invalid URL". This is the entry-point validation before scheme checks and SSRF protection via resolveDownloadHost. It means the string is not a parseable absolute URL at all.

Source

Thrown at internal/validate/url.go:84

	}
	if ip.IsPrivate() {
		return true
	}
	ip16 := ip.To16()
	if ip16 == nil {
		return true
	}
	if ip16[0]&0xfe == 0xfc { // fc00::/7 unique local address
		return true
	}
	return false
}

// ValidateDownloadSourceURL validates a download URL and blocks local/internal targets.
func ValidateDownloadSourceURL(ctx context.Context, rawURL string) error {
	u, err := url.Parse(rawURL)
	if err != nil || u == nil {
		return fmt.Errorf("invalid URL")
	}
	if u.Scheme != "http" && u.Scheme != "https" {
		return fmt.Errorf("only http/https URLs are supported")
	}
	_, err = resolveDownloadHost(ctx, u.Hostname(), net.DefaultResolver.LookupIP)
	return err
}

type downloadLookupIPFunc func(context.Context, string, string) ([]net.IP, error)

func resolveDownloadHost(ctx context.Context, rawHost string, lookupIP downloadLookupIPFunc) ([]net.IP, error) {
	host := strings.TrimSpace(strings.ToLower(rawHost))
	if host == "" {
		return nil, fmt.Errorf("URL host is required")
	}
	if host == "localhost" || strings.HasSuffix(host, ".localhost") {
		return nil, fmt.Errorf("local/internal host is not allowed")
	}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Check the URL for typos and ensure it is complete and on one line.
2. Confirm the string is a single URL, not a list or a path; trim whitespace.
3. Percent-encode special characters in the URL (spaces, control chars).
4. Validate locally first: `python3 -c "import urllib.parse,sys; urllib.parse.urlparse(sys.argv[1])" "$URL"`.

Example fix

// before
lark-cli download url "$URL"   # URL read from file, contains a newline
// after
URL=$(head -n1 urls.txt | tr -d '[:space:]')
lark-cli download url "$URL"

u, err := url.Parse(rawURL)
if err != nil || u == nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("not a valid absolute URL: %q", rawURL)
}

if err := validate.ValidateDownloadSourceURL(ctx, raw); err != nil {
    if strings.Contains(err.Error(), "invalid URL") {
        return fmt.Errorf("check the URL string (complete, single line, percent-encoded): %w", err)
    }
    return err
}

When it happens

Trigger: downloadURLCommand, validateRemoteDocImageSource, or startURLDownload passes a string to ValidateDownloadSourceURL that url.Parse cannot parse — e.g. missing scheme with unparseable characters, unescaped control characters, or malformed percent-encoding.

Common situations: Typo or truncated URL, unquoted shell strings with control characters, input read from a file containing stray whitespace or multiple lines, or a URL list pasted as one value.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• URL host is required
• only http/https URLs are supported
• Invalid cell reference: {cell_ref}
• Invalid A1 range endpoint: {endpoint}
• Invalid A1 range: {range_ref}

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