standard dynamic library plugin loading requires cgo on this

Error message

standard dynamic library plugin loading requires cgo on this platform: %s

What it means

The binary was compiled with CGO_ENABLED=0 (or no C compiler) on a non-Windows platform, so the pluginhost cannot load dynamic-library plugins. The unsupportedLoader stub is selected at build time via the !cgo && !windows build tag and rejects every Open() with this message.

Source

Thrown at internal/pluginhost/loader_unsupported.go:10

//go:build !cgo && !windows

package pluginhost

import "fmt"

type unsupportedLoader struct{}

func (unsupportedLoader) Open(file pluginFile, host *Host) (pluginClient, error) {
	return nil, fmt.Errorf("standard dynamic library plugin loading requires cgo on this platform: %s", file.Path)
}

func defaultPluginLoader() pluginLoader {
	return unsupportedLoader{}
}

View on GitHub (pinned to 78f0c4079e)

Solutions

Rebuild with CGO_ENABLED=1 and a working C compiler (e.g. apt-get install gcc / apk add build-base) installed
For cross-compilation, install a cross C toolchain (e.g. musl-gcc) and set CC accordingly
If dynamic-library plugins are not needed, remove plugin entries from the config so the loader is never invoked

Example fix

# before
docker build  # Dockerfile: ENV CGO_ENABLED=0

# after
# Dockerfile
ENV CGO_ENABLED=1
RUN apk add --no-cache build-base

Defensive patterns

Strategy: validation

Validate before calling

// At startup, before serving:
if runtime.GOOS != "windows" && !cgoAvailable() {
    if len(cfg.Plugins) > 0 {
        log.Fatal("plugins configured but binary built without cgo; rebuild with CGO_ENABLED=1")
    }
}

Prevention

Set CGO_ENABLED=1 explicitly in build scripts and Dockerfiles when plugins are used
Install a C compiler in CI images (gcc / build-base / mingw)
Fail fast at startup if plugins are configured but the loader is the unsupported stub

When it happens

Trigger: Building with CGO_ENABLED=0 (common in Docker scratch/alpine images and distroless CI); missing gcc/clang in the build container; cross-compiling without a C toolchain for the target platform; then configuring any plugin with a .so library path.

Common situations: Docker images that set CGO_ENABLED=0 for static binaries; GoReleaser defaults that disable cgo; development on a machine without build-essential installed.

Related errors

AI-assisted analysis of router-for-me/CLIProxyAPI@78f0c4079e (2026-08-15). Data as JSON: /api/errors/97d96d9f4d9654c1. Report an issue: GitHub.