tursodatabase/turso · error · ArgumentException

invalid config: url is required

Error message

invalid config: url is required

What it means

TursoServerlessConnection validates its options before creating a session and requires a non-empty Url. There is no default endpoint, so constructing a connection without a URL fails fast with this ArgumentException rather than at first execute.

Source

Thrown at bindings/dotnet/src/Turso.Serverless.Client/TursoServerlessConnection.cs:51

    private readonly TursoServerlessConnectionOptions _options;
    private readonly TursoSession _session;
    private readonly SemaphoreSlim _execLock = new(1, 1);
    private bool _isOpen = true;

    public TursoServerlessConnection(TursoServerlessConnectionOptions options)
        : this(options, SharedHttpClient)
    {
    }

    /// <summary>Creates a connection using a caller-provided <see cref="HttpClient"/> (not disposed by this class).</summary>
    public TursoServerlessConnection(TursoServerlessConnectionOptions options, HttpClient httpClient)
    {
        ArgumentNullException.ThrowIfNull(options);
        ArgumentNullException.ThrowIfNull(httpClient);
        if (string.IsNullOrEmpty(options.Url))
        {
            throw new ArgumentException("invalid config: url is required", nameof(options));
        }

        _options = options;
        _session = new TursoSession(options, httpClient);
    }

    /// <summary>
    /// Whether the connection is currently inside a transaction, as reported by the server or
    /// established by a successful cursor transaction-control statement.
    /// </summary>
    public bool InTransaction => _session.InTransaction;

    /// <summary>Executes a SQL statement with optional positional arguments and returns the full result set.</summary>
    public Task<TursoResultSet> ExecuteAsync(string sql, IReadOnlyList<object?>? args = null, TimeSpan? queryTimeout = null, CancellationToken cancellationToken = default)
    {
        return LockedExecuteAsync(SqlArgs.ToStatement(sql, args, namedArgs: null, wantRows: true), queryTimeout, cancellationToken);
    }

View on GitHub (pinned to 244cde92a7)

Solutions

1. Set options.Url to your database URL (libsql://<db>-<org>.turso.io or the https equivalent) together with AuthToken before constructing the connection
2. Read the URL from configuration with a startup check: fail loudly when the env var is missing
3. Add a launch-settings/CI placeholder list of required variables (TURSO_DATABASE_URL, TURSO_AUTH_TOKEN) so omissions surface at deploy time

Example fix

// before
var conn = new TursoServerlessConnection(new TursoServerlessConnectionOptions()); // Url empty

// after
var url = Environment.GetEnvironmentVariable("TURSO_DATABASE_URL")
    ?? throw new InvalidOperationException("TURSO_DATABASE_URL is not set");
var conn = new TursoServerlessConnection(new TursoServerlessConnectionOptions { Url = url });

var url = Environment.GetEnvironmentVariable("TURSO_DATABASE_URL");
if (string.IsNullOrWhiteSpace(url)) throw new InvalidOperationException("TURSO_DATABASE_URL is not configured");

static bool IsConnectionOptionsValid(TursoServerlessConnectionOptions o) => !string.IsNullOrEmpty(o.Url);

try { _conn = new TursoServerlessConnection(opts); } catch (ArgumentException ex) when (ex.Message.Contains("url is required")) { throw new InvalidOperationException("Database URL missing: set TURSO_DATABASE_URL", ex); }

When it happens

Trigger: new TursoServerlessConnection(new TursoServerlessConnectionOptions()) with Url never assigned; Url populated from an unset environment variable so it binds null or empty string.

Common situations: TURSO_DATABASE_URL missing in local .env, CI secrets not injected, or production config binding silently mapping nothing; renaming the env var in one place but not the others.

Related errors

• Auth Token requires a remote Turso URL Data Source.
• Keyword not supported: {keyword}.
• Replica Path requires a remote Turso URL Data Source.
• Sync Interval requires a remote embedded replica connection.
• Tls requires a remote Turso URL Data Source.

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/d5f4e5a8295c0630. Report an issue: GitHub.