langgenius/dify · error · ValueError

KNOWLEDGE_FS_BASE_URL must include a valid port

Error message

KNOWLEDGE_FS_BASE_URL must include a valid port

What it means

Raised by KnowledgeFSConfig.validate_base_url when urlsplit(value).port raises ValueError. Python's urllib raises that only when the port component is syntactically present but not a valid integer in range (e.g. 'http://h:abc' or 'http://h:99999'). Note http/https URLs without an explicit port return None and do NOT trigger this; it requires a malformed explicit port.

Source

Thrown at api/configs/extra/knowledge_fs_config.py:51

            normalized = value.get_secret_value().strip()
            return SecretStr(normalized) if normalized else None
        if isinstance(value, str):
            normalized = value.strip()
            return normalized or None
        return value

    @field_validator("KNOWLEDGE_FS_BASE_URL")
    @classmethod
    def validate_base_url(cls, value: str | None) -> str | None:
        if value is None:
            return None
        parsed = urlsplit(value)
        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
            raise ValueError("KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL")
        try:
            _ = parsed.port
        except ValueError as exc:
            raise ValueError("KNOWLEDGE_FS_BASE_URL must include a valid port") from exc
        if parsed.username or parsed.password or parsed.query or parsed.fragment:
            raise ValueError("KNOWLEDGE_FS_BASE_URL must not include credentials, query, or fragment")
        return value.rstrip("/")

    @model_validator(mode="after")
    def validate_enabled_connection(self) -> "KnowledgeFSConfig":
        if not self.KNOWLEDGE_FS_ENABLED:
            return self
        if bool(self.KNOWLEDGE_FS_BASE_URL) != bool(self.KNOWLEDGE_FS_JWT_SECRET):
            raise ValueError("KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET must be configured together")
        if not self.KNOWLEDGE_FS_BASE_URL:
            raise ValueError("KnowledgeFS connection settings are required when the integration is enabled")
        return self

View on GitHub (pinned to ef8544b173)

Solutions

1. Set KNOWLEDGE_FS_BASE_URL to an absolute http(s) URL with a numeric port in 0-65535, e.g. 'https://kfs.example:8443'.
2. If you want the protocol default port (443/80), omit the port entirely: 'https://kfs.example'.
3. Check for stray characters after the port (trailing slash is fine; letters are not).

Example fix

// before
KNOWLEDGE_FS_BASE_URL=https://kfs.example:abc
// after
KNOWLEDGE_FS_BASE_URL=https://kfs.example:8443

from urllib.parse import urlsplit

def valid_kfs_url(value: str | None) -> bool:
    if value is None:
        return True
    try:
        parsed = urlsplit(value)
    except ValueError:
        return False
    if parsed.scheme not in {'http', 'https'} or not parsed.netloc:
        return False
    try:
        _ = parsed.port
    except ValueError:
        return False
    return not (parsed.username or parsed.password or parsed.query or parsed.fragment)

When it happens

Trigger: Setting KNOWLEDGE_FS_BASE_URL to a value like 'https://kfs.example:abc', 'http://10.0.0.1:99999', or 'http://host:8080a'. Accessing parsed.port on such URLs raises ValueError, which the validator re-raises with this message.

Common situations: Typos in the port, copy-pasting a service mesh sidecar port spec, using an SRV-style 'host:port:proto' string, or a port outside the 0-65535 range.

Related errors

• KNOWLEDGE_FS_BASE_URL must not include credentials, query, o
• KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL
• KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET must be co
• KnowledgeFS connection settings are required when the integr
• PLUGIN_REMOTE_INSTALL_PORT must be a bare port number, got {

AI-assisted analysis of langgenius/dify@ef8544b173 (2026-08-12). Data as JSON: /api/errors/8cc81876f59ee738. Report an issue: GitHub.