github/copilot-sdk · error

err.Error()

Error message

err.Error()

What it means

NewClient panics when ClientOptions.SessionFS fails validateSessionFSConfig; the validation error's message (err.Error()) is passed to panic. The SessionFS option configures a session filesystem backend, and an invalid combination/settings (per validateSessionFSConfig) cannot be used to build a client.

Solutions

1. Read the panic message — it is the validator's error — and correct the offending SessionFS field.
2. Call the same validation logic (or replicate its checks) before constructing the client.
3. If the backend isn't needed, leave SessionFS nil to use the default.

Example fix

// before
client := clientpkg.NewClient(&clientpkg.Options{SessionFS: &clientpkg.SessionFSConfig{}} // invalid: incomplete
)
// after
if err := validateSessionFSConfig(cfg); err != nil {
    return fmt.Errorf("invalid SessionFS config: %w", err)
}
client := clientpkg.NewClient(&clientpkg.Options{SessionFS: cfg})

if opts.SessionFS != nil {
    if err := validateSessionFSConfig(opts.SessionFS); err != nil {
        return fmt.Errorf("invalid SessionFS: %w", err)
    }
}

defer func() {
    if r := recover(); r != nil {
        err = fmt.Errorf("client construction failed: %v", r)
    }
}()
client := clientpkg.NewClient(opts)

When it happens

Trigger: Calling NewClient with a non-nil Options.SessionFS whose configuration violates validateSessionFSConfig's rules (e.g. missing required fields or incompatible settings). The error text comes from that validator, surfaced at go/client.go:336.

Common situations: Configuring a custom session filesystem backend with partially filled options; changing SessionFS settings after an SDK update that tightened validation.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• SessionFS.SessionStatePath is required
• sessionFs.initialCwd is required
• sessionFs.sessionStatePath is required
• sessionFs.conventions must be either 'windows' or 'posix'
• SessionFS.Conventions must be either 'posix' or 'windows'

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

Appendix: source

Thrown at go/client.go:336

			client.cliPath = cliPath
		}
	}

	// Resolve the effective connection token: explicit value if set; else if the SDK
	// spawns its own runtime in TCP mode, generate a UUID; otherwise empty. The
	// in-process transport uses no socket, so it needs no connection token.
	if client.tcpConnectionToken != "" {
		client.effectiveConnectionToken = client.tcpConnectionToken
	} else if !client.useStdio && !client.isExternalServer && !client.useInProcess {
		client.effectiveConnectionToken = uuid.NewString()
	}

	if opts.OnListModels != nil {
		client.onListModels = opts.OnListModels
	}
	if opts.SessionFS != nil {
		if err := validateSessionFSConfig(opts.SessionFS); err != nil {
			panic(err.Error())
		}
	}

	client.options = opts
	validateNewClientForMode(&client.options)
	return client
}

func resolveRuntimeExecutable(explicitPath, bundledRuntimePath string) (string, error) {
	if explicitPath != "" {
		return explicitPath, nil
	}
	if bundledRuntimePath == "" {
		return "", errors.New(
			"managed Copilot runtime unavailable: the embedded bundle does not contain copilot-runtime and adjacent runtime.node; regenerate the bundle, provide an explicit path, or set COPILOT_CLI_PATH",
		)
	}
	return bundledRuntimePath, nil

View on GitHub (pinned to cd8cf15dc3)