BuiltinPluginDirectories must contain only absolute paths

Error message

BuiltinPluginDirectories must contain only absolute paths: %s

What it means

NewClient panics when any entry in ClientOptions.BuiltinPluginDirectories is a relative path. The SDK passes these directories to the native runtime, which resolves them independently of the Go process, so all entries must be absolute to be unambiguous.

Solutions

Convert each entry with filepath.Abs(path) before passing it to NewClient.
Fix the source of the paths (config file, flag) to supply absolute paths.
Reject relative paths at your own config-validation layer with a clear message.

Example fix

// before
dirs := []string{"plugins/builtin"}
client := clientpkg.NewClient(&clientpkg.Options{BuiltinPluginDirectories: dirs})
// after
var dirs []string
for _, p := range []string{"plugins/builtin"} {
    abs, err := filepath.Abs(p)
    if err != nil {
        panic(err)
    }
    dirs = append(dirs, abs)
}
client := clientpkg.NewClient(&clientpkg.Options{BuiltinPluginDirectories: dirs})

Defensive patterns

Strategy: validation

Validate before calling

for _, p := range opts.BuiltinPluginDirectories {
    if !filepath.IsAbs(p) {
        abs, err := filepath.Abs(p)
        if err != nil { return err }
        _ = abs // or reject the path
    }
}

Prevention

Always run filepath.Abs on user/config-supplied plugin paths at load time.
Prefer resolving paths once at startup, not deep in the client.
Add a unit test asserting configured plugin dirs are absolute.

When it happens

Trigger: Calling NewClient with Options.BuiltinPluginDirectories containing a value like "plugins/builtin" or "./x" — any path where filepath.IsAbs fails. Panic raised at go/client.go:242.

Common situations: Building the list from config files or CLI flags that carry relative paths; developing on a machine where the working directory happens to make the relative path look correct.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at go/client.go:242

func NewClient(options *ClientOptions) *Client {
	opts := ClientOptions{}

	client := &Client{
		options:              opts,
		state:                stateDisconnected,
		sessions:             make(map[string]*Session),
		gitHubTokenProviders: make(map[string]GitHubTokenProvider),
		actualHost:           "localhost",
		isExternalServer:     false,
		useStdio:             true,
	}

	if options != nil {
		opts = *options
	}
	for _, path := range opts.BuiltinPluginDirectories {
		if !filepath.IsAbs(path) {
			panic(fmt.Sprintf("BuiltinPluginDirectories must contain only absolute paths: %s", path))
		}
	}
	opts.BuiltinPluginDirectories = append([]string(nil), opts.BuiltinPluginDirectories...)

	// Resolve the connection. An explicit connection always wins; otherwise
	// honor the same process/environment override as the other SDKs.
	connection := opts.Connection
	if connection == nil {
		env := opts.Env
		if env == nil {
			env = os.Environ()
		}
		connection = resolveDefaultConnection(env)
	}
	switch conn := connection.(type) {
	case StdioConnection:
		client.useStdio = true
		client.cliPath = conn.Path

View on GitHub (pinned to cd8cf15dc3)