{"record":{"id":"a1a915f1a4f7dd50","repo":"ipfs/kubo","slug":"linux-musl-not-supported-you-must-build-the-binar","errorCode":null,"errorMessage":"linux-musl not supported, you must build the binary from source for your platform","messagePattern":"linux-musl not supported, you must build the binary from source for your platform","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":278,"sourceCode":"\t\tcmd = exec.CommandContext(ctx, binPath, pathArg, \"-verbose=true\")\n\t}\n\tcmd.Stdout = os.Stdout\n\tcmd.Stderr = os.Stderr\n\treturn cmd.Run()\n}\n\n// fetchMigrations downloads the requested migrations, and returns a slice with\n// the paths of each binary, in the same order specified by needed.\n//\n// Deprecated: This function downloads migration binaries from the internet and will be removed\n// in a future version. Use RunHybridMigrations or RunEmbeddedMigrations instead.\nfunc fetchMigrations(ctx context.Context, fetcher Fetcher, needed []string, destDir string, logger *log.Logger) ([]string, error) {\n\tosv, err := osWithVariant()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif osv == \"linux-musl\" {\n\t\treturn nil, fmt.Errorf(\"linux-musl not supported, you must build the binary from source for your platform\")\n\t}\n\n\tvar wg sync.WaitGroup\n\twg.Add(len(needed))\n\tbins := make([]string, len(needed))\n\t// Download and unpack all requested migrations concurrently.\n\tfor i, name := range needed {\n\t\tlogger.Printf(\"Downloading migration: %s...\", name)\n\t\tgo func(i int, name string) {\n\t\t\tdefer wg.Done()\n\t\t\tdist := path.Join(distMigsRoot, name)\n\t\t\tver, err := LatestDistVersion(ctx, fetcher, dist, false)\n\t\t\tif err != nil {\n\t\t\t\tlogger.Printf(\"could not get latest version of migration %s: %s\", name, err)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tloc, err := FetchBinary(ctx, fetcher, dist, ver, name, destDir)\n\t\t\tif err != nil {","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L260-L296","documentation":"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.","triggerScenarios":"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).","commonSituations":"Running kubo inside Alpine Docker images; minimal musl-based container deployments; CI jobs on Alpine that auto-run repo migrations on daemon start.","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"],"exampleFix":"// before\nFROM alpine:3.19\nCOPY ipfs /usr/local/bin/\n// after\nFROM golang:1.22 AS builder\nRUN git clone https://github.com/ipfs/fs-repo-migrations && cd fs-repo-migrations && go build -o /bin/migrations ./...\nFROM debian:bookworm-slim\nCOPY --from=builder /bin/migrations /usr/local/bin/migrations\nCOPY ipfs /usr/local/bin/","handlingStrategy":"fallback","validationCode":"osv, err := migration.OSWithVariant() // or detect musl via ldd --version\nif osv == \"linux-musl\" {\n    log.Println(\"musl detected: build migrations from source or use glibc image\")\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"linux-musl not supported\") {\n    return fmt.Errorf(\"on musl, pre-build migration binaries and add them to PATH: %w\", err)\n}","preventionTips":["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"],"tags":["migrations","platform-support","linux","musl"],"backgroundTag":"musl-platform-unsupported","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}