langgenius/dify · error · ValueError

KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET must be co

Error message

KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET must be configured together

What it means

Raised by the after-model validator validate_enabled_connection when exactly one of KNOWLEDGE_FS_BASE_URL / KNOWLEDGE_FS_JWT_SECRET is set (XOR). The integration requires both because the URL identifies the gateway and the JWT secret signs service tokens; a half-configured state would either fail to connect or send unsigned requests.

Source

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

        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 BOTH KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET (>=32 chars) in the same environment.
2. If disabling the integration, set KNOWLEDGE_FS_ENABLED=false and unset both.
3. Verify the JWT secret was not truncated by shell quoting and meets min_length=32.

Example fix

// before
KNOWLEDGE_FS_ENABLED=true
KNOWLEDGE_FS_BASE_URL=https://kfs.example:8443
// (KNOWLEDGE_FS_JWT_SECRET missing)
// after
KNOWLEDGE_FS_ENABLED=true
KNOWLEDGE_FS_BASE_URL=https://kfs.example:8443
KNOWLEDGE_FS_JWT_SECRET=<32+ char shared secret>

def kfs_pair_ok(url: str | None, secret: str | None) -> bool:
    return bool(url) == bool(secret) and (not secret or len(secret) >= 32)

When it happens

Trigger: Enabling KNOWLEDGE_FS_ENABLED=true with KNOWLEDGE_FS_BASE_URL set but KNOWLEDGE_FS_JWT_SECRET unset (or under 32 chars, which normalizes to None), or vice versa.

Common situations: Operator configures the URL in one env file and the secret in another but forgets one; or the JWT secret is blanked/short so the before-validator converts it to None.

Related errors

• KnowledgeFS connection settings are required when the integr
• KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL
• KNOWLEDGE_FS_BASE_URL must include a valid port
• KNOWLEDGE_FS_BASE_URL must not include credentials, query, o
• PUBSUB_REDIS_URL must be set when default Redis URL cannot b

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