github/copilot-sdk · error · InvalidOperationException

CreateSessionFsProvider is required in the session config…

Error message

CreateSessionFsProvider is required in the session config when CopilotClientOptions.SessionFs is configured.

What it means

When CopilotClientOptions.SessionFs is configured, the client requires a `CreateSessionFsProvider` handler in the session configuration to construct the filesystem provider instance for each session. The handler passed down from the session config was null, so the client cannot build the SessionFs and throws.

Solutions

Set CreateSessionFsProvider in the session configuration to a factory returning your ISessionFsProvider implementation.
If you do not intend to use a custom session filesystem, remove CopilotClientOptions.SessionFs so this path is skipped.
Check the code path that builds the session config to ensure the handler is assigned before the session starts.

Example fix

// before
options.SessionFs = new SessionFsConfig { Capabilities = new() { Sqlite = true } };

// after
options.SessionFs = new SessionFsConfig { Capabilities = new() { Sqlite = true } };
sessionConfig.CreateSessionFsProvider = _ => new MySessionFsProvider();

Defensive patterns

Strategy: validation

Validate before calling

if (options.SessionFs is not null && sessionConfig.CreateSessionFsProvider is null)
    throw new InvalidOperationException("SessionFs configured but CreateSessionFsProvider missing");

Try / catch

try
{
    session = await client.CreateSessionAsync(sessionConfig);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("CreateSessionFsProvider is required"))
{
    logger.LogError(ex, "Session config missing CreateSessionFsProvider while SessionFs options are set");
}

Prevention

Set SessionFs options and the CreateSessionFsProvider handler together in one factory method.
Add a startup assertion that both are configured or both are absent.
Review SDK upgrade notes for new required session-config fields.

When it happens

Trigger: CopilotClientOptions.SessionFs is set (with a SessionFsConfig) but the session-level createSessionFsHandler delegate is null when InitializeSessionFs runs (Client.cs:2154).

Common situations: Configuring SessionFs options globally but forgetting to supply the CreateSessionFsProvider factory in the per-session config; wiring only part of the session setup after upgrading the SDK; building the session config from a partial/deserialized object where the handler could not be carried over.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at dotnet/src/Client.cs:2154

    {
        if (_clientGlobalApis?.LlmInference is null)
        {
            return;
        }

        await Rpc.LlmInference.SetProviderAsync(cancellationToken);
    }

    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();

View on GitHub (pinned to cd8cf15dc3)