commaai/openpilot · error · URLFileException

Failed to {method} {url}: {e}

Error message

Failed to {method} {url}: {e}

What it means

URLFile._request wraps urllib3's MaxRetryError when an HTTP request to the remote file exhausts retries — DNS failure, connection refused, TLS error, or repeated timeouts. It is openpilot's remote-file layer, so it appears whenever reading a route/segment over HTTP.

Source

Thrown at openpilot/tools/lib/url_file.py:95

    #  Caching enabled by default, can be disabled with DISABLE_FILEREADER_CACHE=1, or overwritten by the cache input
    self._force_download = int(os.environ.get("DISABLE_FILEREADER_CACHE", "0")) == 1
    if cache is not None:
      self._force_download = not cache

    if not self._force_download:
      os.makedirs(Paths.download_cache_root(), exist_ok=True)

  def __enter__(self):
    return self

  def __exit__(self, exc_type, exc_value, traceback) -> None:
    pass

  def _request(self, method: str, url: str, headers: dict[str, str] | None = None) -> BaseHTTPResponse:
    try:
      return URLFile.pool_manager().request(method, url, timeout=self._timeout, headers=headers)
    except MaxRetryError as e:
      raise URLFileException(f"Failed to {method} {url}: {e}") from e

  def get_length_online(self) -> int:
    response = self._request('HEAD', self._url)
    if not (200 <= response.status <= 299):
      return -1
    length = response.headers.get('content-length', 0)
    return int(length)

  def get_length(self) -> int:
    if self._length is not None:
      return self._length

    file_length_path = os.path.join(Paths.download_cache_root(), hash_url(self._url) + "_length")
    if not self._force_download and os.path.exists(file_length_path):
      with open(file_length_path) as file_length:
        content = file_length.read()
        self._length = int(content)
        return self._length

View on GitHub (pinned to 516ec1e682)

Solutions

1. Verify basic connectivity to the exact URL: curl -I <url>
2. Fix proxy/DNS: set HTTPS_PROXY correctly or disable the VPN, then retry
3. Add retry-with-backoff around the read, and cache downloaded segments locally so repeated runs don't re-hit the network

Example fix

# before
dat = FileReader('https://cdn.../rlog.bz2').read()

# after
from openpilot.tools.lib.url_file import URLFileException
for attempt in range(3):
    try:
        dat = FileReader('https://cdn.../rlog.bz2').read()
        break
    except URLFileException:
        if attempt == 2: raise
        time.sleep(2 ** attempt)

import requests

def url_reachable(url: str) -> bool:
    try:
        return requests.head(url, timeout=10).status_code < 500
    except requests.RequestException:
        return False

from openpilot.tools.lib.url_file import URLFileException
for attempt in range(3):
    try:
        dat = FileReader(url).read()
        break
    except URLFileException as e:
        if attempt == 2 or 'Failed to' not in str(e):
            raise
        time.sleep(2 ** attempt)

When it happens

Trigger: Any URLFile/FileReader read on an http(s) path while offline, behind a blocking proxy, with a bad URL, or when the data backend is temporarily down; retries exceeded under flaky Wi-Fi.

Common situations: Corporate proxy/VPN rejecting api.comma.ai or cdn hosts; typo'd URL; airplane-mode CI; transient CDN outage.

Related errors

• Remote file is empty or doesn't exist: {self._url}
• Expected 206 or 200 response {r.status} ({self._url})
• Missing multipart boundary ({self._url})
• Expected {len(ranges)} parts, got {len(parts)} ({self._url})
• {func.__name__} failed after retry

AI-assisted analysis of commaai/openpilot@516ec1e682 (2026-08-15). Data as JSON: /api/errors/c6181e9089282645. Report an issue: GitHub.