What causes "CreateSessionFsProvider returned null." in github/copilot-sdk?

Make CreateSessionFsProvider always return a valid ISessionFsProvider instance, or throw with a clear message inside the factory.

github/copilot-sdk · error · InvalidOperationException

CreateSessionFsProvider returned null.

Error message

CreateSessionFsProvider returned null.

What it means

The session config did supply a CreateSessionFsProvider handler, but invoking it returned null. The client needs a concrete provider instance to attach to the session's filesystem APIs, so it throws instead of assigning a null provider.

Solutions

Make CreateSessionFsProvider always return a valid ISessionFsProvider instance, or throw with a clear message inside the factory.
Fix the null-returning branch in the factory (failed lookup, missing registration, unsupported platform).
If the provider genuinely cannot be created, fail earlier with an explicit configuration error instead of returning null.

Example fix

// before
sessionConfig.CreateSessionFsProvider = _ => _lazyProvider?.Value; // null if not created

// after
sessionConfig.CreateSessionFsProvider = _ => _lazyProvider?.Value
    ?? throw new InvalidOperationException("SessionFs provider not initialized");

Defensive patterns

Strategy: validation

Validate before calling

sessionConfig.CreateSessionFsProvider = session =>
    CreateProvider(session) ?? throw new InvalidOperationException("Provider factory returned null");

Try / catch

try
{
    session = await client.CreateSessionAsync(sessionConfig);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("returned null"))
{
    logger.LogError(ex, "CreateSessionFsProvider factory returned null");
}

Prevention

Never write a provider factory with a nullable return path; throw explicitly on failure.
Test the factory against every supported platform/configuration.
Fail fast in DI setup if the provider implementation is unregistered.

When it happens

Trigger: createSessionFsHandler(session) evaluates to null at Client.cs:2159 — the factory delegate returns null (or a null-valued expression) when called during session initialization with SessionFs configured.

Common situations: A factory like `_ => FindProvider()` where the lookup fails and returns null; conditional creation code returning null on platforms where the provider isn't available; forgetting the `new` in `MyProvider()` and returning a null field; DI container resolving no registration.

Related errors

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

Appendix: source

Thrown at dotnet/src/Client.cs:2159

        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();
        var usedFallbackPing = false;
        var maxVersion = SdkProtocolVersion.GetVersion();
        int? serverVersion;
        try
        {

View on GitHub (pinned to cd8cf15dc3)