langgenius/dify · error · ValueError

KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL

Error message

KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL

What it means

Pydantic ValidationError (raised as ValueError inside the field_validator) when KNOWLEDGE_FS_BASE_URL is set but fails the absolute-HTTP(S) URL check: the scheme is not http/https or the netloc (host) is empty. The validator runs after optional-string normalization and before the model_validator that checks enabled-connection pairing.

Source

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

    )
    @classmethod
    def normalize_optional_string(cls, value: object) -> object:
        if isinstance(value, SecretStr):
            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 a full absolute URL with scheme, e.g. https://knowledge.internal:8080.
2. Ensure there is no leading/trailing whitespace and no scheme typos.
3. Remove any embedded credentials, query (?), or fragment (#) from the URL.
4. If the integration is not in use, leave KNOWLEDGE_FS_BASE_URL unset and KNOWLEDGE_FS_ENABLED=false.

Example fix

# before
KNOWLEDGE_FS_BASE_URL=knowledge.internal:8080
# -> 'KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL'

# after
KNOWLEDGE_FS_BASE_URL=https://knowledge.internal:8080

from urllib.parse import urlsplit

def is_valid_knowledge_fs_base_url(value: str | None) -> bool:
    if not value:
        return True  # None is allowed when disabled
    parsed = urlsplit(value)
    return parsed.scheme in {"http", "https"} and bool(parsed.netloc)

def is_absolute_http_url(value: str | None) -> bool:
    if not value:
        return True
    parsed = urlsplit(value)
    return parsed.scheme in {"http", "https"} and bool(parsed.netloc)

from pydantic import ValidationError
try:
    cfg = KnowledgeFSConfig()
except ValidationError as exc:
    print(f"KnowledgeFS config invalid: {exc}")
    raise

When it happens

Trigger: Triggered at config load when KNOWLEDGE_FS_BASE_URL is a non-empty string whose urlsplit yields a scheme outside {http, https} (e.g. 'ftp://', '') or no netloc (e.g. 'localhost' without scheme, or a bare path).

Common situations: The URL was set without a scheme (e.g. 'knowledge.internal:8080'), used a wrong scheme, or is empty after stripping (though empty is normalized to None and allowed). Also common when copying a value that includes credentials, query, or fragment (caught by the next validator).

Related errors

• KNOWLEDGE_FS_BASE_URL must include a valid port
• KNOWLEDGE_FS_BASE_URL must not include credentials, query, o
• KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET must be co
• KnowledgeFS connection settings are required when the integr
• NEW_USER_DEFAULT_MODELS entries must use 'model_type:provide

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