langchain-ai/deepagents · error · ValueError

remote source must not contain a query string or fragment

Error message

remote source must not contain a query string or fragment

What it means

Raised by `_validate_remote_source_url` when the URL contains a query string ('?...') or fragment ('#...'). The library normalizes remote sources to a canonical URL, and query/fragment parts would make two textual spellings of the same source compare unequal and complicate caching, so they are rejected outright.

Source

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

        msg = "remote source must not contain whitespace or control characters"
        raise ValueError(msg)
    try:
        parsed = urlsplit(source)
    except ValueError as exc:
        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

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Remove the '?' query and '#' fragment, keeping only scheme://host/path
  2. If auth was passed via query parameters, move it to headers or an env-based credential
  3. Strip tracking parameters (utm_*, v=, token=) before assigning the source
  4. If you need to reference part of a file, handle that after fetch, not in the source URL

Example fix

// before
RemoteSource(source="https://example.com/config.toml?token=abc#shared")
// after
RemoteSource(source="https://example.com/config.toml")
Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse

def has_query_or_fragment(source: str) -> bool:
    parsed = urlparse(source)
    return bool(parsed.query or parsed.fragment)

if has_query_or_fragment(src):
    src = src.split("?", 1)[0].split("#", 1)[0]

Type guard

def is_bare_https_path(value: str) -> bool:
    parsed = urlparse(value)
    return not parsed.query and not parsed.fragment

Try / catch

try:
    RemoteSource(source=src)
except ValueError as exc:
    if "query string or fragment" in str(exc):
        raise ConfigError(f"strip query/fragment from remote source: {src!r}") from exc
    raise

Prevention

When it happens

Trigger: Constructing the remote-source dataclass with URLs like 'https://example.com/config.toml?token=abc' or 'https://example.com/config.toml#section' — parsed.query or parsed.fragment is truthy.

Common situations: Copying a URL from a browser address bar that includes a tracking query ('?utm_source=...'); appending a cache-buster ('?v=2'); pasting a share link with a '#subsection' fragment; using a signed URL with query auth.

Related errors

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