{"record":{"id":"bca00f75ed74416a","repo":"langgenius/dify","slug":"knowledge-fs-base-url-must-be-an-absolute-http-s","errorCode":null,"errorMessage":"KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL","messagePattern":"KNOWLEDGE_FS_BASE_URL must be an absolute HTTP\\(S\\) URL","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"api/configs/extra/knowledge_fs_config.py","lineNumber":47,"sourceCode":"    )\n    @classmethod\n    def normalize_optional_string(cls, value: object) -> object:\n        if isinstance(value, SecretStr):\n            normalized = value.get_secret_value().strip()\n            return SecretStr(normalized) if normalized else None\n        if isinstance(value, str):\n            normalized = value.strip()\n            return normalized or None\n        return value\n\n    @field_validator(\"KNOWLEDGE_FS_BASE_URL\")\n    @classmethod\n    def validate_base_url(cls, value: str | None) -> str | None:\n        if value is None:\n            return None\n        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":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/api/configs/extra/knowledge_fs_config.py#L29-L65","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Set KNOWLEDGE_FS_BASE_URL to a full absolute URL with scheme, e.g. https://knowledge.internal:8080.","Ensure there is no leading/trailing whitespace and no scheme typos.","Remove any embedded credentials, query (?), or fragment (#) from the URL.","If the integration is not in use, leave KNOWLEDGE_FS_BASE_URL unset and KNOWLEDGE_FS_ENABLED=false."],"exampleFix":"# before\nKNOWLEDGE_FS_BASE_URL=knowledge.internal:8080\n# -> 'KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL'\n\n# after\nKNOWLEDGE_FS_BASE_URL=https://knowledge.internal:8080","handlingStrategy":"validation","validationCode":"from urllib.parse import urlsplit\n\ndef is_valid_knowledge_fs_base_url(value: str | None) -> bool:\n    if not value:\n        return True  # None is allowed when disabled\n    parsed = urlsplit(value)\n    return parsed.scheme in {\"http\", \"https\"} and bool(parsed.netloc)","typeGuard":"def is_absolute_http_url(value: str | None) -> bool:\n    if not value:\n        return True\n    parsed = urlsplit(value)\n    return parsed.scheme in {\"http\", \"https\"} and bool(parsed.netloc)","tryCatchPattern":"from pydantic import ValidationError\ntry:\n    cfg = KnowledgeFSConfig()\nexcept ValidationError as exc:\n    print(f\"KnowledgeFS config invalid: {exc}\")\n    raise","preventionTips":["Always include the scheme: https://host:port, not host:port.","Strip whitespace and avoid credentials, query, or fragment in the URL.","If the integration is unused, leave KNOWLEDGE_FS_ENABLED=false and the URL unset.","Pair KNOWLEDGE_FS_BASE_URL with KNOWLEDGE_FS_JWT_SECRET (>=32 chars) when enabled."],"tags":["backend","config","pydantic","validation","url","knowledge-fs"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}