golang/go · error

unknown load command 0x

Error message

unknown load command 0x%x (%s)

What it means

While rewriting load commands during DWARF combination, the linker walks every load command to adjust offsets. It has a hardcoded set of known command types (LC_SEGMENT, LC_SYMTAB, LC_DYLD_INFO, LC_VERSION_MIN_*, LC_BUILD_VERSION, the many LC_*_DYLIB variants, etc.). Any command not in that set is rejected, because the linker cannot safely relocate an unknown command's offsets and would corrupt the binary.

Solutions

1. Upgrade the Go toolchain to a release that supports your macOS/Xcode load commands.
2. Downgrade/lock the Xcode SDK to one supported by your Go version (`xcode-select`).
3. Avoid combining DWARF (`-ldflags='-s -w'`) if you cannot upgrade Go, since the unknown command is only hit in that path.
4. If you injected custom load commands via a post-processor, remove them before combineDwarf.

Example fix

# before: older Go meets newer Xcode load commands
go1.20 build -o bin/app ./...

# after: use a Go release that knows the new LC_* commands
go1.22 build -o bin/app ./...

# Check for load commands the current Go may not know
otool -l bin/app | grep -oE 'LC_[A-Z_]+' | sort -u
# Compare against the list in macho_combine_dwarf.go to spot unknown ones

# Fall back to a stripped build (skipping combineDwarf) on unknown LC
set +e
go build -o bin/app ./...
rc=$?
set -e
if [ $rc -ne 0 ]; then
  echo 'unknown load command; building stripped' >&2
  go build -ldflags='-s -w' -o bin/app ./...
fi

When it happens

Trigger: Linking on a newer macOS/Xcode whose `ld` emits a load command the Go toolchain version predates (e.g. a new LC_* added after the Go release); combining DWARF into a binary produced by a non-Go, non-Apple toolchain that emits uncommon commands; a binary post-processed by a tool that injected a custom load command.

Common situations: Using the latest Xcode/macOS with an older Go release; mixing toolchains in a monorepo; building for a newer Apple platform (visionOS, etc.) before Go added support.

Related errors

• missing __DWARF segment
• missing __LINKEDIT segment
• missing __text section
• no room to add dwarf info. Need at least
• invalid version

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/0639e8820375b690. Report an issue: GitHub.

Appendix: source

Thrown at src/cmd/link/internal/ld/macho_combine_dwarf.go:213

		case imacho.LC_UUID:
			var u uuidCmd
			err = reader.ReadAt(0, &u)
			if err == nil && len(buildinfo) > 0 {
				clear(u.Uuid[:])
				copy(u.Uuid[:], buildinfo)
				err = reader.WriteAt(0, &u)
			}
		case macho.LoadCmdDylib, macho.LoadCmdThread, macho.LoadCmdUnixThread,
			imacho.LC_PREBOUND_DYLIB, imacho.LC_VERSION_MIN_MACOSX, imacho.LC_VERSION_MIN_IPHONEOS, imacho.LC_SOURCE_VERSION,
			imacho.LC_MAIN, imacho.LC_LOAD_DYLINKER, imacho.LC_LOAD_WEAK_DYLIB, imacho.LC_REEXPORT_DYLIB, imacho.LC_RPATH, imacho.LC_ID_DYLIB,
			imacho.LC_SYMSEG, imacho.LC_LOADFVMLIB, imacho.LC_IDFVMLIB, imacho.LC_IDENT, imacho.LC_FVMFILE, imacho.LC_PREPAGE, imacho.LC_ID_DYLINKER,
			imacho.LC_ROUTINES, imacho.LC_SUB_FRAMEWORK, imacho.LC_SUB_UMBRELLA, imacho.LC_SUB_CLIENT, imacho.LC_SUB_LIBRARY, imacho.LC_TWOLEVEL_HINTS,
			imacho.LC_PREBIND_CKSUM, imacho.LC_ROUTINES_64, imacho.LC_LAZY_LOAD_DYLIB, imacho.LC_LOAD_UPWARD_DYLIB, imacho.LC_DYLD_ENVIRONMENT,
			imacho.LC_LINKER_OPTION, imacho.LC_LINKER_OPTIMIZATION_HINT, imacho.LC_VERSION_MIN_TVOS, imacho.LC_VERSION_MIN_WATCHOS,
			imacho.LC_VERSION_NOTE, imacho.LC_BUILD_VERSION:
			// Nothing to update
		default:
			err = fmt.Errorf("unknown load command 0x%x (%s)", int(cmd.Cmd), cmd.Cmd)
		}
		if err != nil {
			return err
		}
	}
	// Do the final update of the DWARF segment's load command.
	return machoUpdateDwarfHeader(&reader, compressedSects, dwarfsize, dwarfstart, realdwarf)
}

// machoCompressSections tries to compress the DWARF segments in dwarfm,
// returning the updated sections and segment contents, nils if the sections
// weren't compressed, or an error if there was a problem reading dwarfm.
func machoCompressSections(ctxt *Link, dwarfm *macho.File) ([]*macho.Section, []byte, error) {
	if !ctxt.compressDWARF {
		return nil, nil, nil
	}

	dwarfseg := dwarfm.Segment("__DWARF")

View on GitHub (pinned to b6b368adc5)