gitHubToken and useLoggedInUser cannot be used with…

Error message

gitHubToken and useLoggedInUser cannot be used with RuntimeConnection.forUri (external server manages its own auth)

What it means

When the session_fs capabilities in the client options declare sqlite support, _initialize_session() type-checks the provider produced by create_session_fs_handler and raises this ValueError if it is not an instance of SessionFsSqliteProvider. Declaring the sqlite capability promises the library a SQLite-backed provider; a plain SessionFsProvider cannot satisfy it.

Solutions

Make the returned provider subclass SessionFsSqliteProvider (from copilot.session_fs_provider) and implement its SQLite methods.
Remove the "sqlite" capability from the session_fs capabilities config if SQLite is not actually supported.
Fix create_session_fs_handler so it instantiates the intended SQLite-capable provider.

Example fix

// before
class MyFsProvider(SessionFsProvider): ...
create_session_fs_handler=lambda s: MyFsProvider(s)
// after
from copilot.session_fs_provider import SessionFsSqliteProvider
class MyFsProvider(SessionFsSqliteProvider): ...
create_session_fs_handler=lambda s: MyFsProvider(s)

Defensive patterns

Strategy: type-guard

Validate before calling

from copilot.session_fs_provider import SessionFsSqliteProvider
provider = create_session_fs_handler(session)
if caps.get("sqlite") and not isinstance(provider, SessionFsSqliteProvider):
    raise TypeError("sqlite capability requires a SessionFsSqliteProvider subclass")

Type guard

def is_sqlite_provider(p) -> bool:
    from copilot.session_fs_provider import SessionFsSqliteProvider
    return isinstance(p, SessionFsSqliteProvider)

Try / catch

try:
    session = await client.create_session(
        ..., create_session_fs_handler=make_fs_handler)
except ValueError as e:
    if "SessionFsSqliteProvider" in str(e):
        ...  # fix provider class hierarchy or drop the sqlite capability

Prevention

Subclass SessionFsSqliteProvider when declaring the sqlite capability.
Keep the capabilities dict and the provider implementation in sync.
Add a unit test that instantiates your handler and isinstance-checks the result.

When it happens

Trigger: Client options set session_fs capabilities {"sqlite": true}, but the create_session_fs_handler returns a provider class that does not subclass SessionFsSqliteProvider.

Common situations: Implementing a custom filesystem provider after enabling sqlite in capabilities copied from an example; refactoring the provider so it no longer inherits SessionFsSqliteProvider; registering a mock/stub in tests while capabilities still declare sqlite.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at nodejs/src/client.ts:608

     *   connection: RuntimeConnection.forStdio({ path: "/usr/local/bin/copilot" }),
     *   logLevel: "debug",
     * });
     * ```
     */
    constructor(options: CopilotClientOptions = {}) {
        // Resolve the connection mode. `_internalConnection` is set by
        // `joinSession()` to opt into the parent-process stdio path; consumers
        // should always go through the public `connection` field.
        const conn: InternalRuntimeConnection =
            options._internalConnection ??
            options.connection ??
            CopilotClient.resolveDefaultConnection();

        if (
            conn.kind === "uri" &&
            (options.gitHubToken !== undefined || options.useLoggedInUser !== undefined)
        ) {
            throw new Error(
                "gitHubToken and useLoggedInUser cannot be used with RuntimeConnection.forUri (external server manages its own auth)"
            );
        }
        if (conn.kind === "inprocess" && options.workingDirectory !== undefined) {
            throw new Error(
                "workingDirectory is not supported with RuntimeConnection.forInProcess(): the in-process " +
                    "transport hosts the runtime in this process, so honoring it would require mutating the " +
                    "shared process-global cwd. Change the host process's working directory before " +
                    "constructing the client instead."
            );
        }
        if (conn.kind === "inprocess" && options.env !== undefined) {
            throw new Error(
                "env is not supported with RuntimeConnection.forInProcess(): the in-process transport loads " +
                    "the native runtime into the shared host process, whose single environment block cannot " +
                    "carry per-client values. Set the variables on the host process environment instead."
            );
        }

View on GitHub (pinned to cd8cf15dc3)