github/copilot-sdk · error

builtinPluginDirectories must contain only absolute paths

Error message

builtinPluginDirectories must contain only absolute paths: ${path}

What it means

Constructor validation error: the builtinPluginDirectories option array contains a relative path. The client requires every entry to be absolute so plugin resolution is unambiguous regardless of the process's current working directory; '${path}' failed that check.

Solutions

1. Convert the offending path to an absolute path with path.resolve() or path.join(rootDir, p) before passing it in builtinPluginDirectories
2. Remove the relative entry if the plugin is not needed
3. If the path comes from user/config input, normalize it at load time: entries.map(p => path.isAbsolute(p) ? p : path.resolve(baseDir, p))

When it happens

Trigger: Thrown at nodejs/src/client.ts:660 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at nodejs/src/client.ts:660

                    "(RuntimeConnection.forStdio/forTcp), not both. Prefer the connection-level env for " +
                    "child-process transports."
            );
        }
        if (conn.kind === "tcp" && conn.connectionToken !== undefined) {
            if (typeof conn.connectionToken !== "string" || conn.connectionToken.length === 0) {
                throw new Error("connectionToken must be a non-empty string");
            }
        }

        this.connectionConfig = conn;

        if (options.sessionFs) {
            this.validateSessionFsConfig(options.sessionFs);
        }
        if (options.builtinPluginDirectories) {
            for (const path of options.builtinPluginDirectories) {
                if (!isAbsolute(path)) {
                    throw new Error(
                        `builtinPluginDirectories must contain only absolute paths: ${path}`
                    );
                }
            }
            this.builtinPluginDirectories = [...options.builtinPluginDirectories];
        }

        // Pre-parse the URI host/port and mark as external if applicable.
        if (conn.kind === "uri") {
            const { host, port } = this.parseCliUrl(conn.url);
            this.actualHost = host;
            this.runtimePort = port;
            this.isExternalServer = true;
        } else if (conn.kind === "parent-process") {
            this.isExternalServer = true;
        }

        // Effective TCP connection token: explicit, else auto-generated when we

View on GitHub (pinned to cd8cf15dc3)