linux-musl not supported, you must build the binary from sou

Error message

linux-musl not supported, you must build the binary from source for your platform

What it means

fetchMigrations refuses to download prebuilt migration binaries when the OS variant is linux-musl (Alpine and other musl-based systems), because the official ipfs migration binaries are not published for that platform. The error tells the user to build the migration binaries from source themselves.

Source

Thrown at repo/fsrepo/migrations/migrations.go:278

		cmd = exec.CommandContext(ctx, binPath, pathArg, "-verbose=true")
	}
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr
	return cmd.Run()
}

// fetchMigrations downloads the requested migrations, and returns a slice with
// the paths of each binary, in the same order specified by needed.
//
// Deprecated: This function downloads migration binaries from the internet and will be removed
// in a future version. Use RunHybridMigrations or RunEmbeddedMigrations instead.
func fetchMigrations(ctx context.Context, fetcher Fetcher, needed []string, destDir string, logger *log.Logger) ([]string, error) {
	osv, err := osWithVariant()
	if err != nil {
		return nil, err
	}
	if osv == "linux-musl" {
		return nil, fmt.Errorf("linux-musl not supported, you must build the binary from source for your platform")
	}

	var wg sync.WaitGroup
	wg.Add(len(needed))
	bins := make([]string, len(needed))
	// Download and unpack all requested migrations concurrently.
	for i, name := range needed {
		logger.Printf("Downloading migration: %s...", name)
		go func(i int, name string) {
			defer wg.Done()
			dist := path.Join(distMigsRoot, name)
			ver, err := LatestDistVersion(ctx, fetcher, dist, false)
			if err != nil {
				logger.Printf("could not get latest version of migration %s: %s", name, err)
				return
			}
			loc, err := FetchBinary(ctx, fetcher, dist, ver, name, destDir)
			if err != nil {

View on GitHub (pinned to 329838acdf)

Solutions

Build the required fs-repo-migration binaries from source (github.com/ipfs/fs-repo-migrations) and put them in PATH
Switch the container/deployment to a glibc-based image (debian/ubuntu) so downloaded binaries run
Use the daemon's embedded migrations where possible (repo versions >= 16 need no external binaries)
Pin a glibc-based base image in your Dockerfile for kubo

Example fix

// before
FROM alpine:3.19
COPY ipfs /usr/local/bin/
// after
FROM golang:1.22 AS builder
RUN git clone https://github.com/ipfs/fs-repo-migrations && cd fs-repo-migrations && go build -o /bin/migrations ./...
FROM debian:bookworm-slim
COPY --from=builder /bin/migrations /usr/local/bin/migrations
COPY ipfs /usr/local/bin/

Defensive patterns

Strategy: fallback

Validate before calling

osv, err := migration.OSWithVariant() // or detect musl via ldd --version
if osv == "linux-musl" {
    log.Println("musl detected: build migrations from source or use glibc image")
}

Try / catch

if err != nil && strings.Contains(err.Error(), "linux-musl not supported") {
    return fmt.Errorf("on musl, pre-build migration binaries and add them to PATH: %w", err)
}

Prevention

Use glibc-based base images (debian/ubuntu) for kubo deployments
Pre-build fs-repo-migrations from source on Alpine
Prefer embedded migrations (repo >= 16) to avoid external binaries
Detect musl in Dockerfile build stage and fail fast with guidance

When it happens

Trigger: Running RunMigration (which calls fetchMigrations) on a musl-based Linux system, detected by osWithVariant() returning "linux-musl" (typically when the ipfs binary itself is statically linked with musl).

Common situations: Running kubo inside Alpine Docker images; minimal musl-based container deployments; CI jobs on Alpine that auto-run repo migrations on daemon start.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/a1a915f1a4f7dd50. Report an issue: GitHub.