golang/go · error

unknown load command 0x%x (%s)

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.

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)

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 __LINKEDIT segment
• missing __DWARF segment
• missing __text section
• no room to add dwarf info. Need at least %d padding bytes, f
• subprogram DIE high not convertible to uint64

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