{"record":{"id":"b62a440486c4eb24","repo":"tursodatabase/turso","slug":"remote-url-is-not-available","errorCode":null,"errorMessage":"remote_url is not available","messagePattern":"remote_url is not available","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"bindings/python/turso/lib_sync.py","lineNumber":140,"sourceCode":"    if req_kind.body is not None:\n        # req_kind.body is PyBytes -> bytes\n        body = bytes(req_kind.body)\n\n    headers_list = []\n    if req_kind.headers is not None:\n        headers_list = _headers_iter_to_pairs(req_kind.headers)  # list[(k,v)]\n\n    try:\n        base_url = ctx.base_url()\n    except Exception as e:\n        io_item.poison(f\"remote url unavailable: {e}\")\n        return\n\n    # Build full URL\n    url = base_url if base_url else req_kind.url\n    if not url:\n        io_item.poison(\"remote url unavailable\")\n        raise RuntimeError(\"remote_url is not available\")\n    url = _join_url(url, path)\n\n    # Build request\n    request = urllib.request.Request(url=url, data=body, method=method)\n    # Add provided headers\n    seen_auth = False\n    for k, v in headers_list:\n        request.add_header(k, v)\n        if k.lower() == \"authorization\":\n            seen_auth = True\n\n    # Add Authorization if not present and token provided\n    token = None\n    try:\n        token = ctx.token()\n    except Exception:\n        # token resolver failure -> bubble up as IO error\n        io_item.poison(\"auth token resolver failed\")","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/python/turso/lib_sync.py#L122-L158","documentation":"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.","triggerScenarios":"`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).","commonSituations":"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.","solutions":["Pass a concrete non-empty remote_url to turso.sync.connect: `turso.sync.connect(\"local.db\", remote_url=\"libsql://...\", auth_token=\"...\")`","If remote_url is a callable, make it always return a valid URL or raise a clear configuration error itself — never empty string","Validate configuration at startup (assert the env var is present and non-empty) so the failure happens at boot, not mid-sync"],"exampleFix":"# before\nconn = turso.sync.connect(\"local.db\")  # remote_url forgotten/None\n\n# after\nconn = turso.sync.connect(\n    \"local.db\",\n    remote_url=os.environ[\"TURSO_REMOTE_URL\"],  # fails fast if unset\n    auth_token=os.environ[\"TURSO_AUTH_TOKEN\"],\n)","handlingStrategy":"validation","validationCode":"import os\n\nremote_url = os.environ.get(\"TURSO_REMOTE_URL\")\nif not remote_url:\n    raise RuntimeError(\n        \"TURSO_REMOTE_URL is not set; sync cannot reach any endpoint. \"\n        \"Set it to your libsql:// / https:// endpoint.\"\n    )\nconn = turso.sync.connect(\"local.db\", remote_url=remote_url, auth_token=os.environ.get(\"TURSO_AUTH_TOKEN\"))","typeGuard":null,"tryCatchPattern":"try:\n    conn = turso.sync.connect(\"local.db\", remote_url=resolve_remote_url())\nexcept RuntimeError as e:\n    if \"remote_url is not available\" in str(e):\n        raise SystemExit(\"sync remote URL missing — check TURSO_REMOTE_URL\") from e\n    raise","preventionTips":["Fail fast at startup: require and validate the remote URL env var before any sync call","If remote_url is a lambda, make it raise a clear error (or return a valid URL) — never an empty string","Watch for lazy config loading that evaluates the lambda before settings exist","Remember libsql:// and turso:// schemes are auto-upgraded to https:// by connect()"],"tags":["python","sync","remote-url","configuration","missing-env-var"],"backgroundTag":"missing-endpoint-url","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}