langgenius/dify · error · ValueError

KNOWLEDGE_FS_BASE_URL must not include credentials, query, o

Error message

KNOWLEDGE_FS_BASE_URL must not include credentials, query, or fragment

What it means

Raised by KnowledgeFSConfig.validate_base_url when the parsed URL contains userinfo (username/password), a query string, or a fragment. The validator wants a clean origin URL because the gateway base is used verbatim to build outbound requests and sign JWTs; credentials must come from KNOWLEDGE_FS_JWT_SECRET, not the URL.

Source

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

        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. Strip credentials, query, and fragment from the URL; supply only scheme://host:port.
2. Move authentication into KNOWLEDGE_FS_JWT_SECRET (min 32 chars) rather than the URL.
3. If a query/fragment appears unintentionally, remove trailing characters from the env value.

Example fix

// before
KNOWLEDGE_FS_BASE_URL=https://svc:pwd@kfs.example:8443?env=prod
// after
KNOWLEDGE_FS_BASE_URL=https://kfs.example:8443
KNOWLEDGE_FS_JWT_SECRET=<32+ char shared secret>

from urllib.parse import urlsplit

def is_clean_origin(value: str) -> bool:
    p = urlsplit(value)
    return not (p.username or p.password or p.query or p.fragment)

When it happens

Trigger: Setting KNOWLEDGE_FS_BASE_URL to 'https://user:pass@kfs.example:8443', 'https://kfs.example:8443?token=x', or 'https://kfs.example:8443#section'.

Common situations: Copy-pasting a connection string from a secrets manager that bundles inline auth, or appending a query param expecting it to be forwarded to the gateway.

Related errors

• KNOWLEDGE_FS_BASE_URL must include a valid port
• 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
• ELASTICSEARCH_API_KEY is required when using Elastic Cloud

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