weaviate/weaviate · error

invalid baseURL: %w

Error message

invalid baseURL: %w

What it means

ValidateBaseURL (when BaseURLValidationEnabled) parses a module baseURL with url.Parse to enforce SSRF/HTTPS safety rules. If the string cannot be parsed as a URL at all (malformed scheme/percent-encoding/control characters), the function returns this wrapped error.

Source

Thrown at usecases/modulecomponents/validate_baseurl.go:77

		ip.IsPrivate() ||
		ip.IsLinkLocalUnicast() ||
		ip.IsLinkLocalMulticast() ||
		ip.IsUnspecified()
}

// ValidateBaseURL validates a module baseURL (class config or X-*-Baseurl
// header) against SSRF abuse: https-only, non-empty host, and not pointing at
// an internal address (by IP literal, by blocked hostname/suffix, or by DNS
// resolution). It is a no-op unless MODULES_VALIDATE_BASE_URL is enabled; an
// empty baseURL means "use the module default" and is allowed.
func ValidateBaseURL(baseURL string) error {
	if !BaseURLValidationEnabled() || baseURL == "" {
		return nil
	}

	parsed, err := url.Parse(baseURL)
	if err != nil {
		return fmt.Errorf("invalid baseURL: %w", err)
	}
	if parsed.Scheme != "https" {
		return fmt.Errorf("baseURL must use HTTPS")
	}
	host := parsed.Hostname()
	if host == "" {
		return fmt.Errorf("baseURL must have a non-empty host")
	}

	if ip := net.ParseIP(host); ip != nil {
		if isDisallowedIP(ip) {
			return fmt.Errorf("baseURL cannot target internal addresses")
		}
		return nil
	}

	lower := strings.ToLower(host)
	for _, blocked := range blockedHostnames {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Fix the BASE_URL to a well-formed absolute URL, e.g. https://api.example.com.
2. Trim whitespace/newlines from the env value; percent-encode special characters properly (%25 for a literal %).
3. Validate locally with a quick script: python3 -c "import urllib.parse; urllib.parse.urlparse('YOUR_URL')" or a Go url.Parse test before deploying.
4. If you control policy, note validation can be disabled via the BaseURLValidation toggle, but fixing the URL is the correct fix.

Example fix

// before
BASE_URL=https://api.example.com/v1 %
// after
BASE_URL=https://api.example.com/v1

// Validate the module base URL before startup
u := os.Getenv("BASE_URL")
if _, err := url.Parse(strings.TrimSpace(u)); err != nil {
    panic(fmt.Sprintf("BASE_URL is not a parseable URL: %v", err))
}

func isParseableURL(s string) bool {
    _, err := url.Parse(strings.TrimSpace(s))
    return err == nil
}

if err := modulecomponents.ValidateBaseURL(baseURL); err != nil {
    return fmt.Errorf("rejecting module config, fix BASE_URL (well-formed absolute URL): %w", err)
}

When it happens

Trigger: Configuring a module (e.g. text2vec-openai, generative modules) with BASE_URL containing characters that make url.Parse fail — raw spaces, unescaped '%' (e.g. "https://api.example.com/%zz"), or embedded control characters.

Common situations: Copy-pasting a URL with a trailing space/newline from documentation; hand-encoding query strings with stray '%'; templating tools injecting whitespace.

Related errors

• baseURL must have a non-empty host
• client not found for provider: %s
• baseURL must use HTTPS
• module '%s'
• init module %d (%q)

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/956db8d65e9a91a3. Report an issue: GitHub.