langgenius/dify · error · ValueError

KnowledgeFS connection settings are required when the integr

Error message

KnowledgeFS connection settings are required when the integration is enabled

What it means

Raised by validate_enabled_connection when KNOWLEDGE_FS_ENABLED is true and KNOWLEDGE_FS_BASE_URL is falsy after the XOR check. In practice the preceding XOR guard makes this branch reachable only when BOTH base_url and jwt_secret are empty, i.e. the integration was switched on without any connection settings.

Source

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

        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

Provide KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET alongside the enabled flag.
If you did not intend to use KnowledgeFS, set KNOWLEDGE_FS_ENABLED=false.

Example fix

// before
KNOWLEDGE_FS_ENABLED=true
// after
KNOWLEDGE_FS_ENABLED=false
// OR provide connection settings:
KNOWLEDGE_FS_ENABLED=true
KNOWLEDGE_FS_BASE_URL=https://kfs.example:8443
KNOWLEDGE_FS_JWT_SECRET=<32+ char secret>

Defensive patterns

Strategy: validation

Validate before calling

def kfs_enabled_complete(enabled: bool, url: str | None, secret: str | None) -> bool:
    return (not enabled) or bool(url and secret)

Prevention

Gate the feature flag on the presence of both connection settings.
Use a config template that sets all three together.
Run a smoke check on startup that logs the resolved integration state.

When it happens

Trigger: Setting KNOWLEDGE_FS_ENABLED=true while leaving both KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET unset/blank.

Common situations: Flipping the feature flag on in a default env, or a deployment template enabling the flag without the connection block.

Related errors

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