github/copilot-sdk · error · ValueError

builtin_plugin_directories must contain only absolute paths

Error message

builtin_plugin_directories must contain only absolute paths: {path}

What it means

builtin_plugin_directories must contain only absolute paths. During CopilotClient construction each entry is checked with os.path.isabs(); a relative path raises ValueError because the runtime cannot reliably resolve relative plugin directories.

Solutions

Convert each entry with os.path.abspath()/Path.resolve() before passing
Store absolute paths in configuration files
Compute plugin directories from a known base at startup

Example fix

// before
client = CopilotClient(builtin_plugin_directories=["plugins"])
// after
client = CopilotClient(builtin_plugin_directories=[os.path.abspath("plugins")])

Defensive patterns

Strategy: validation

Validate before calling

bad = [p for p in dirs if not os.path.isabs(p)]
if bad:
    raise ValueError(f"relative plugin paths: {bad}")
client = CopilotClient(builtin_plugin_directories=dirs)

Type guard

def all_absolute(paths: list[str]) -> bool:
    return all(os.path.isabs(p) for p in paths)

Try / catch

try:
    client = CopilotClient(builtin_plugin_directories=dirs)
except ValueError as e:
    if "absolute paths" in str(e):
        dirs = [os.path.abspath(p) for p in dirs]
        client = CopilotClient(builtin_plugin_directories=dirs)

Prevention

Always resolve config-supplied paths with Path.resolve() at load time
Store absolute paths in configuration
Check os.path.isabs() in a config validation step at startup

When it happens

Trigger: Passing a relative path like 'plugins' or './plugins' in options.builtin_plugin_directories when constructing the client.

Common situations: Hardcoded relative paths in config; paths built from user input without resolution; working directory differs between dev and prod so a previously working relative path moved.

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/c86d2dbb62ebb361. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/client.py:1681

            telemetry=telemetry,
            session_fs=session_fs,
            request_handler=request_handler,
            session_idle_timeout_seconds=session_idle_timeout_seconds,
            enable_remote_sessions=enable_remote_sessions,
            client_info=client_info,
            on_list_models=on_list_models,
            on_github_telemetry=on_github_telemetry,
            mode=mode,
        )
        connection = (
            options.connection
            if options.connection is not None
            else _resolve_default_connection(os.environ)
        )
        _validate_environment_options(options, connection)
        for path in options.builtin_plugin_directories:
            if not os.path.isabs(path):
                raise ValueError(
                    f"builtin_plugin_directories must contain only absolute paths: {path}"
                )
        _require_storage_for_empty_mode(
            mode=options.mode,
            base_directory=options.base_directory,
            session_fs_set=options.session_fs is not None,
            is_uri_connection=isinstance(connection, UriRuntimeConnection),
        )

        self._options: _CopilotClientOptions = options
        self._connection: RuntimeConnection = connection
        self._on_list_models = options.on_list_models
        self._on_github_telemetry = options.on_github_telemetry

        # Resolve connection-mode-specific state.
        self._actual_host: str = "localhost"
        self._is_external_server: bool = isinstance(connection, UriRuntimeConnection)
        self._cli_path_source: str | None = None

View on GitHub (pinned to cd8cf15dc3)