github/copilot-sdk · error · ArgumentException

CopilotClientOptions.BuiltinPluginDirectories must contain…

Error message

CopilotClientOptions.BuiltinPluginDirectories must contain only absolute paths: <path>

What it means

The CopilotClient constructor validates that every entry in CopilotClientOptions.BuiltinPluginDirectories is an absolute (fully qualified) path. Any relative path causes an immediate ArgumentException naming the offending path.

Solutions

1. Convert each directory to an absolute path with Path.GetFullPath(Path.Combine(baseDir, rel)) before assigning
2. Expand '~' yourself via Environment.GetFolderPath for user-relative dirs
3. Fix the configured value in appsettings/config to a fully qualified path

Example fix

// before
options.BuiltinPluginDirectories = new[] { "plugins/builtin" };
// after
options.BuiltinPluginDirectories = new[] { Path.GetFullPath("plugins/builtin", AppContext.BaseDirectory) };

if (dirs.Any(d => !Path.IsPathFullyQualified(d))) throw new ArgumentException("BuiltinPluginDirectories must all be absolute");

try { client = new CopilotClient(options); } catch (ArgumentException ex) when (ex.Message.Contains("absolute paths")) { log.LogError(ex, "Plugin dir config invalid"); }

When it happens

Trigger: new CopilotClient(options) where options.BuiltinPluginDirectories contains a relative path like "plugins" or "./builtin" or "~/.copilot/plugins".

Common situations: Hardcoding relative paths in app config; relying on '~' expansion which .NET does not perform; configs authored on one OS and reused on another; test fixtures using relative paths that worked via the working directory elsewhere.

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

• ConnectionToken must be a non-empty string or null.
• UriRuntimeConnection.Url must be a non-empty string.
• Unsupported RuntimeConnection type
• Invalid entry '*': there is no bare wildcard. Use `new…
• CopilotClient is in Mode = CopilotClientMode.Empty but the…

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

Appendix: source

Thrown at dotnet/src/Client.cs:146

    /// // Connect to an existing runtime
    /// var client = new CopilotClient(new CopilotClientOptions { Connection = RuntimeConnection.ForUri("localhost:3000") });
    ///
    /// // Custom runtime path with specific log level
    /// var client = new CopilotClient(new CopilotClientOptions
    /// {
    ///     Connection = RuntimeConnection.ForStdio(path: "/usr/local/bin/copilot"),
    ///     LogLevel = CopilotLogLevel.Debug
    /// });
    /// </code>
    /// </example>
    public CopilotClient(CopilotClientOptions? options = null)
    {
        _options = options ?? new();
        _connection = _options.Connection ?? ResolveDefaultConnection(_options);
        _builtinPluginDirectories = _options.BuiltinPluginDirectories?.ToArray() ?? [];
        foreach (var path in _builtinPluginDirectories.Where(path => !IsFullyQualifiedPath(path)))
        {
            throw new ArgumentException(
                $"{nameof(CopilotClientOptions)}.{nameof(CopilotClientOptions.BuiltinPluginDirectories)} " +
                $"must contain only absolute paths: {path}",
                nameof(options));
        }

        switch (_connection)
        {
            case StdioRuntimeConnection:
                break;

            case InProcessRuntimeConnection:
                break;

            case TcpRuntimeConnection tcp:
                if (tcp.ConnectionToken is { Length: 0 })
                {
                    throw new ArgumentException("ConnectionToken must be a non-empty string or null.", nameof(options));
                }

View on GitHub (pinned to cd8cf15dc3)