jd-opensource/joyagent-jdgenie · error · ValueError

服务器URL不能为空且必须是字符串类型

Error message

服务器URL不能为空且必须是字符串类型

What it means

genie-client's _validate_server_url raises ValueError when server_url is falsy (None or empty string) or not a str instance. The client cannot function without a server URL, so __init__ validates it eagerly.

Solutions

1. Pass a valid non-empty server URL string to the client constructor
2. Set the environment variable or config field supplying the URL
3. Load config with a required-key check before constructing the client
4. Ensure the value is a str, not another type (e.g. coerce or reject early)

Example fix

# before
client = GenieClient(server_url=os.getenv("SERVER_URL"))
# after
server_url = os.getenv("SERVER_URL")
if not server_url:
    raise ValueError("SERVER_URL env var must be set")
client = GenieClient(server_url=server_url)

def get_server_url() -> str:
    url = os.getenv("SERVER_URL")
    if not url or not isinstance(url, str):
        raise ValueError("SERVER_URL must be set to a non-empty string")
    return url

client = GenieClient(server_url=get_server_url())

def is_valid_server_url(url: object) -> bool:
    return isinstance(url, str) and bool(url)

try:
    client = GenieClient(server_url=server_url)
except ValueError as e:
    logging.error("client init failed: %s", e)
    raise SystemExit(1)

When it happens

Trigger: Instantiating GenieClient() with server_url=None or "" — e.g. reading from an unset env var or a missing config key, or passing a non-string value like a dict/int by mistake.

Common situations: Missing SERVER_URL environment variable; YAML/JSON config where the key is absent; refactors that pass a config object instead of the URL string.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• 服务器URL必须以http://或https://开头
• 不支持的数据源类型:
• Invalid tool_choice: " + toolChoice
• step_index is required for mark_step command
• 请检查sql是否正确

AI-assisted analysis of jd-opensource/joyagent-jdgenie@2417e0b8b6 (2026-09-08). Data as JSON: /api/errors/b07433c5b9d7b8d7. Report an issue: GitHub.

Appendix: source

Thrown at genie-client/app/client.py:62

        logger.debug(f"SSE客户端初始化完成 - 服务器: {self.server_url}, 超时: {self.timeout}s")

    @staticmethod
    def _validate_server_url(server_url: str) -> str:
        """
        验证服务器URL的有效性

        Args:
            server_url: 待验证的服务器URL

        Returns:
            验证后的服务器URL

        Raises:
            ValueError: 当URL无效时抛出
        """
        if not server_url or not isinstance(server_url, str):
            raise ValueError("服务器URL不能为空且必须是字符串类型")

        # 简单的URL格式验证
        if not (server_url.startswith('http://') or server_url.startswith('https://')):
            raise ValueError("服务器URL必须以http://或https://开头")

        return server_url.rstrip('/')  # 移除末尾的斜杠

    def _configure_from_entity(self, entity: HeaderEntity) -> None:
        """
        根据 HeaderEntity 配置客户端参数

        Args:
            entity: 包含配置信息的实体对象
        """
        try:
            if entity.timeout is not None:
                self.timeout = max(1, int(entity.timeout))  # 确保超时时间至少为1秒
                logger.debug(f"设置连接超时时间: {self.timeout}s")

View on GitHub (pinned to 2417e0b8b6)