langchain-ai/deepagents · error · ValueError

remote_source must be a validated absolute HTTPS URL

Error message

remote_source must be a validated absolute HTTPS URL

What it means

Raised in `__post_init__` (types.py:137) when the URL fails validation entirely: `_validate_remote_source_url` raised a ValueError (non-HTTPS, credentials, query/fragment, bad port, or non-ASCII/unparseable), and it is re-raised with the generic message that remote_source must be a validated absolute HTTPS URL. The original specific reason is chained via `from exc`.

Source

Thrown at libs/code/deepagents_code/configuration/types.py:137

        text, so "only a validated URL reaches here" is a security invariant.
        It held by convention -- one construction site in each of two modules
        -- and `ProviderStatus` is public, so a third site is a rejected
        source, credentials and all, in a `doctor` row. This restates the
        canonical remote-source validator and also requires its normalized
        output: the point is that an unvalidated string cannot get in.

        Raises:
            ValueError: If `remote_source` is not the normalized output of the
                remote-source validator.
        """
        source = self.remote_source
        if source is None:
            return
        msg = "remote_source must be a validated absolute HTTPS URL"
        try:
            normalized = _validate_remote_source_url(source)
        except ValueError as exc:
            raise ValueError(msg) from exc
        if normalized != source:
            raise ValueError(msg)

    @property
    def usable(self) -> bool:
        """Whether the provider can safely participate in resolution.

        `MISSING` is usable because no file at an authoritative path means the
        administrator deployed no policy. `INDETERMINATE` is not: the path
        itself is a guess, so an empty read proves nothing about what policy
        the administrator deployed.
        """
        return self.health in {ProviderHealth.OK, ProviderHealth.MISSING}


@dataclass(frozen=True, slots=True)
class TomlSnapshot:
    """One parsed TOML source and its health.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pre-normalize the URL through the library's own validation/normalization helper before constructing the object, then assign the normalized string
2. Fix the underlying defect indicated by the chained __cause__ (scheme, credentials, query/fragment, port, or ASCII)
3. Convert local paths to hosted HTTPS URLs — file paths are not valid remote sources
4. For IDNs, use the punycode (ASCII) form of the hostname

Example fix

// before
RemoteProviderDescriptor(remote_source="/home/me/config.toml")  # not a URL
// after
RemoteProviderDescriptor(remote_source="https://config.example.com/me/config.toml")

def check_remote_source(source: str) -> str:
    from deepagents_code.configuration.types import _validate_remote_source_url
    return _validate_remote_source_url(source)  # raises with specific reason

normalized = check_remote_source(candidate)  # call before constructing

def looks_like_https_url(value: object) -> bool:
    from urllib.parse import urlparse
    return (
        isinstance(value, str)
        and value.isascii()
        and urlparse(value).scheme.lower() == "https"
        and bool(urlparse(value).hostname)
    )

try:
    descriptor = RemoteProviderDescriptor(remote_source=src)
except ValueError as exc:
    logger.debug("underlying reason: %s", exc.__cause__)
    raise ConfigError(f"remote_source {src!r} is not a validated HTTPS URL: {exc.__cause__}") from exc

When it happens

Trigger: Constructing the descriptor dataclass with a remote_source that fails any rule in _validate_remote_source_url — e.g. a non-string/unparseable value, non-ASCII characters ('https://exämple.com/x.toml'), scheme missing, credentials, query, fragment, or bad port.

Common situations: Loading config from a TOML/env value that was never normalized; internationalized domain names pasted in Unicode form; empty or malformed strings produced by string interpolation; passing a local file path ('file:///...' or '/home/me/config.toml') where an HTTPS URL is required.

Related errors

• remote source must be an absolute HTTPS URL
• Remote marketplace sources must use https
• {what} must be absolute: {path}
• Home directory is not absolute: {launch_home}. Set $HOME to
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: unknown fil

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/429ee38c2e19de19. Report an issue: GitHub.