langchain-ai/deepagents · error · ValueError

remote source has an invalid port

Error message

remote source has an invalid port

What it means

Raised by `_validate_remote_source_url` when `parsed.port` raises ValueError, i.e. the URL contains a syntactically invalid port (non-numeric or out of range, e.g. 'https://example.com:99999/x' or 'https://example.com:abc/x'). The library re-raises with a clearer message before reconstructing the normalized netloc.

Source

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

        msg = "remote source is not a valid URL"
        raise ValueError(msg) from exc
    if not source.isascii():
        msg = "remote source must contain only ASCII URI characters"
        raise ValueError(msg)
    if parsed.scheme.lower() != "https" or not parsed.hostname:
        msg = "remote source must be an absolute HTTPS URL"
        raise ValueError(msg)
    if parsed.username is not None or parsed.password is not None:
        msg = "remote source must not contain credentials"
        raise ValueError(msg)
    if parsed.query or parsed.fragment:
        msg = "remote source must not contain a query string or fragment"
        raise ValueError(msg)
    try:
        port = parsed.port
    except ValueError as exc:
        msg = "remote source has an invalid port"
        raise ValueError(msg) from exc
    host = parsed.hostname.rstrip(".")
    netloc = f"[{host}]" if ":" in host else host
    if port is not None:
        netloc = f"{netloc}:{port}"
    return parsed._replace(scheme="https", netloc=netloc).geturl()


@dataclass(frozen=True, slots=True)
class ProviderStatus:
    """Health and safe diagnostic detail for one provider."""

    name: str
    path: Path | None
    health: ProviderHealth
    detail: str | None = None
    remote_source: str | None = field(default=None, kw_only=True)
    """Validated URL this status came from, when `path` is only a trust anchor.

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Correct or remove the port — omit it entirely for the default HTTPS port 443
  2. Ensure the port is a plain integer between 1 and 65535
  3. Check for doubled colons or stray characters around the port in the URL

Example fix

// before
RemoteSource(source="https://example.com:99999/config.toml")
// after
RemoteSource(source="https://example.com:8443/config.toml")
Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse

def has_valid_port(source: str) -> bool:
    try:
        urlparse(source).port
    except ValueError:
        return False
    return True

if not has_valid_port(src):
    raise ConfigError(f"invalid port in remote source: {src!r}")

Type guard

def is_parseable_port_url(value: str) -> bool:
    try:
        urlparse(value).port
        return True
    except ValueError:
        return False

Try / catch

try:
    RemoteSource(source=src)
except ValueError as exc:
    if "invalid port" in str(exc):
        raise ConfigError(f"fix the port in remote source: {src!r}") from exc
    raise

Prevention

When it happens

Trigger: Constructing the remote-source dataclass with a URL whose port is non-numeric, empty after ':', or above 65535 — the urllib.parse `.port` accessor raises and the code re-raises 'remote source has an invalid port'.

Common situations: Typos like 'https:/example.com:8443a/...' from hand-editing; double colons ('https://example.com::443/'); pasting 'host:port' pairs where the port field contains a service name ('https://example.com:https/').

Related errors

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