{"record":{"id":"8cc81876f59ee738","repo":"langgenius/dify","slug":"knowledge-fs-base-url-must-include-a-valid-port","errorCode":null,"errorMessage":"KNOWLEDGE_FS_BASE_URL must include a valid port","messagePattern":"KNOWLEDGE_FS_BASE_URL must include a valid port","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"api/configs/extra/knowledge_fs_config.py","lineNumber":51,"sourceCode":"            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":33,"sourceCodeEnd":65,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/api/configs/extra/knowledge_fs_config.py#L33-L65","documentation":"Raised by KnowledgeFSConfig.validate_base_url when urlsplit(value).port raises ValueError. Python's urllib raises that only when the port component is syntactically present but not a valid integer in range (e.g. 'http://h:abc' or 'http://h:99999'). Note http/https URLs without an explicit port return None and do NOT trigger this; it requires a malformed explicit port.","triggerScenarios":"Setting KNOWLEDGE_FS_BASE_URL to a value like 'https://kfs.example:abc', 'http://10.0.0.1:99999', or 'http://host:8080a'. Accessing parsed.port on such URLs raises ValueError, which the validator re-raises with this message.","commonSituations":"Typos in the port, copy-pasting a service mesh sidecar port spec, using an SRV-style 'host:port:proto' string, or a port outside the 0-65535 range.","solutions":["Set KNOWLEDGE_FS_BASE_URL to an absolute http(s) URL with a numeric port in 0-65535, e.g. 'https://kfs.example:8443'.","If you want the protocol default port (443/80), omit the port entirely: 'https://kfs.example'.","Check for stray characters after the port (trailing slash is fine; letters are not)."],"exampleFix":"// before\nKNOWLEDGE_FS_BASE_URL=https://kfs.example:abc\n// after\nKNOWLEDGE_FS_BASE_URL=https://kfs.example:8443","handlingStrategy":"validation","validationCode":"from urllib.parse import urlsplit\n\ndef valid_kfs_url(value: str | None) -> bool:\n    if value is None:\n        return True\n    try:\n        parsed = urlsplit(value)\n    except ValueError:\n        return False\n    if parsed.scheme not in {'http', 'https'} or not parsed.netloc:\n        return False\n    try:\n        _ = parsed.port\n    except ValueError:\n        return False\n    return not (parsed.username or parsed.password or parsed.query or parsed.fragment)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate KNOWLEDGE_FS_BASE_URL with urlsplit in a pre-deploy config check.","Never include credentials or query strings in the base URL; use KNOWLEDGE_FS_JWT_SECRET.","Use explicit numeric ports to avoid ambiguity."],"tags":["config","pydantic","knowledge-fs","url-validation"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}