{"record":{"id":"6fd5a354493d9a00","repo":"langgenius/dify","slug":"knowledgefs-connection-settings-are-required-when","errorCode":null,"errorMessage":"KnowledgeFS connection settings are required when the integration is enabled","messagePattern":"KnowledgeFS connection settings are required when the integration is enabled","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"api/configs/extra/knowledge_fs_config.py","lineNumber":63,"sourceCode":"        parsed = urlsplit(value)\n        if parsed.scheme not in {\"http\", \"https\"} or not parsed.netloc:\n            raise ValueError(\"KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL\")\n        try:\n            _ = parsed.port\n        except ValueError as exc:\n            raise ValueError(\"KNOWLEDGE_FS_BASE_URL must include a valid port\") from exc\n        if parsed.username or parsed.password or parsed.query or parsed.fragment:\n            raise ValueError(\"KNOWLEDGE_FS_BASE_URL must not include credentials, query, or fragment\")\n        return value.rstrip(\"/\")\n\n    @model_validator(mode=\"after\")\n    def validate_enabled_connection(self) -> \"KnowledgeFSConfig\":\n        if not self.KNOWLEDGE_FS_ENABLED:\n            return self\n        if bool(self.KNOWLEDGE_FS_BASE_URL) != bool(self.KNOWLEDGE_FS_JWT_SECRET):\n            raise ValueError(\"KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET must be configured together\")\n        if not self.KNOWLEDGE_FS_BASE_URL:\n            raise ValueError(\"KnowledgeFS connection settings are required when the integration is enabled\")\n        return self\n","sourceCodeStart":45,"sourceCodeEnd":65,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/api/configs/extra/knowledge_fs_config.py#L45-L65","documentation":"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.","triggerScenarios":"Setting KNOWLEDGE_FS_ENABLED=true while leaving both KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET unset/blank.","commonSituations":"Flipping the feature flag on in a default env, or a deployment template enabling the flag without the connection block.","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."],"exampleFix":"// before\nKNOWLEDGE_FS_ENABLED=true\n// after\nKNOWLEDGE_FS_ENABLED=false\n// OR provide connection settings:\nKNOWLEDGE_FS_ENABLED=true\nKNOWLEDGE_FS_BASE_URL=https://kfs.example:8443\nKNOWLEDGE_FS_JWT_SECRET=<32+ char secret>","handlingStrategy":"validation","validationCode":"def kfs_enabled_complete(enabled: bool, url: str | None, secret: str | None) -> bool:\n    return (not enabled) or bool(url and secret)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["config","pydantic","knowledge-fs","required-field"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}