tursodatabase/turso · critical · RuntimeError

remote_url is not available

Error message

remote_url is not available

What it means

Raised inside the sync HTTP IO callback (_process_http_item): the callback resolves the configured base URL via ctx.base_url() (the remote_url given to turso.sync.connect, which may be a lambda evaluated per request) and falls back to the URL carried by the request itself; when both are empty there is no endpoint to talk to. The pending IO item is poisoned with "remote url unavailable" and RuntimeError("remote_url is not available") propagates.

Source

Thrown at bindings/python/turso/lib_sync.py:140

    if req_kind.body is not None:
        # req_kind.body is PyBytes -> bytes
        body = bytes(req_kind.body)

    headers_list = []
    if req_kind.headers is not None:
        headers_list = _headers_iter_to_pairs(req_kind.headers)  # list[(k,v)]

    try:
        base_url = ctx.base_url()
    except Exception as e:
        io_item.poison(f"remote url unavailable: {e}")
        return

    # Build full URL
    url = base_url if base_url else req_kind.url
    if not url:
        io_item.poison("remote url unavailable")
        raise RuntimeError("remote_url is not available")
    url = _join_url(url, path)

    # Build request
    request = urllib.request.Request(url=url, data=body, method=method)
    # Add provided headers
    seen_auth = False
    for k, v in headers_list:
        request.add_header(k, v)
        if k.lower() == "authorization":
            seen_auth = True

    # Add Authorization if not present and token provided
    token = None
    try:
        token = ctx.token()
    except Exception:
        # token resolver failure -> bubble up as IO error
        io_item.poison("auth token resolver failed")

View on GitHub (pinned to bad083fafb)

Solutions

  1. Pass a concrete non-empty remote_url to turso.sync.connect: `turso.sync.connect("local.db", remote_url="libsql://...", auth_token="...")`
  2. If remote_url is a callable, make it always return a valid URL or raise a clear configuration error itself — never empty string
  3. Validate configuration at startup (assert the env var is present and non-empty) so the failure happens at boot, not mid-sync

Example fix

# before
conn = turso.sync.connect("local.db")  # remote_url forgotten/None

# after
conn = turso.sync.connect(
    "local.db",
    remote_url=os.environ["TURSO_REMOTE_URL"],  # fails fast if unset
    auth_token=os.environ["TURSO_AUTH_TOKEN"],
)
Defensive patterns

Strategy: validation

Validate before calling

import os

remote_url = os.environ.get("TURSO_REMOTE_URL")
if not remote_url:
    raise RuntimeError(
        "TURSO_REMOTE_URL is not set; sync cannot reach any endpoint. "
        "Set it to your libsql:// / https:// endpoint."
    )
conn = turso.sync.connect("local.db", remote_url=remote_url, auth_token=os.environ.get("TURSO_AUTH_TOKEN"))

Try / catch

try:
    conn = turso.sync.connect("local.db", remote_url=resolve_remote_url())
except RuntimeError as e:
    if "remote_url is not available" in str(e):
        raise SystemExit("sync remote URL missing — check TURSO_REMOTE_URL") from e
    raise

Prevention

When it happens

Trigger: `turso.sync.connect("local.db")` with remote_url omitted, None, or "", then any sync operation that needs the network (create/bootstrap, pull, push). Also a remote_url callable/lambda that returns None or "" at request time (e.g. reads an env var that is unset in this context).

Common situations: Missing or misspelled TURSO_DATABASE_URL env var; config loaded lazily so the lambda evaluates before settings exist; empty string from YAML/JSON config; CI or a teammate's machine running without sync environment variables.

Related errors

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/b62a440486c4eb24. Report an issue: GitHub.