github/copilot-sdk · error · InvalidOperationException

SessionFsConfig declares capabilities.sqlite but the…

Error message

SessionFsConfig declares capabilities.sqlite but the provider does not implement ISessionFsSqliteProvider.

What it means

SessionFsConfig declares `capabilities.sqlite = true`, advertising SQLite support to the server, but the provider instance created by CreateSessionFsProvider does not implement the ISessionFsSqliteProvider interface. The client refuses to attach a provider that cannot honor the declared capability, since the server would issue SQLite operations the provider can't serve.

Solutions

Implement ISessionFsSqliteProvider on your provider class (or have your wrapper delegate to one).
Set Capabilities.Sqlite = false in SessionFsConfig if you don't need SQLite support.
Use a SQLite-capable provider implementation that matches the declared capabilities.

Example fix

// before
public class MyFsProvider : ISessionFsProvider { ... }

// after
public class MyFsProvider : ISessionFsProvider, ISessionFsSqliteProvider { ... }

Defensive patterns

Strategy: validation

Validate before calling

if (config.SessionFs?.Capabilities?.Sqlite == true &&
    provider is not ISessionFsSqliteProvider)
    throw new InvalidOperationException("Provider must implement ISessionFsSqliteProvider");

Type guard

static bool SupportsDeclaredSqlite(SessionFsProvider p, SessionFsConfig c) =>
    c.Capabilities?.Sqlite != true || p is ISessionFsSqliteProvider;

Try / catch

try
{
    session = await client.CreateSessionAsync(sessionConfig);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("ISessionFsSqliteProvider"))
{
    logger.LogError(ex, "SessionFs provider does not implement declared sqlite capability");
}

Prevention

Derive Capabilities from what the provider actually implements instead of hard-coding Sqlite=true.
Add a startup self-check pairing each declared capability with an interface check.
Keep capability flags and provider interfaces updated together in one change.

When it happens

Trigger: _options.SessionFs.Capabilities?.Sqlite == true and the created provider fails the `provider is not ISessionFsSqliteProvider` check at Client.cs:2163 during session FS initialization.

Common situations: Copying a SessionFsConfig with Sqlite=true from a sample while using a basic in-memory or file provider; upgrading the config but not the provider class; a provider wrapper/decorator class that doesn't forward the ISessionFsSqliteProvider interface.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/5a1a2a755e2887c7. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Client.cs:2163

    private void ConfigureSessionFsHandlers(CopilotSession session, Func<CopilotSession, SessionFsProvider>? createSessionFsHandler)
    {
        if (_options.SessionFs is null)
        {
            return;
        }

        if (createSessionFsHandler is null)
        {
            throw new InvalidOperationException(
                "CreateSessionFsProvider is required in the session config when CopilotClientOptions.SessionFs is configured.");
        }

        var provider = createSessionFsHandler(session)
            ?? throw new InvalidOperationException("CreateSessionFsProvider returned null.");

        if (_options.SessionFs.Capabilities?.Sqlite == true && provider is not ISessionFsSqliteProvider)
        {
            throw new InvalidOperationException(
                "SessionFsConfig declares capabilities.sqlite but the provider does not implement ISessionFsSqliteProvider.");
        }

        session.ClientSessionApis.SessionFs = provider;
    }

    private async Task VerifyProtocolVersionAsync(Connection connection, CancellationToken cancellationToken)
    {
        var handshakeTimestamp = Stopwatch.GetTimestamp();
        var usedFallbackPing = false;
        var maxVersion = SdkProtocolVersion.GetVersion();
        int? serverVersion;
        try
        {
            var token = _ffiHost is not null
                ? null // FFI hosting is an ungated in-process connection; no token.
                : _connection switch
                {

View on GitHub (pinned to cd8cf15dc3)