internal error: import symbol %q with no underlying sym

Error message

internal error: import symbol %q with no underlying sym

What it means

The Go linker found an import symbol (a symbol whose name starts with `__imp_`) but the underlying symbol it is supposed to import (the name after the `__imp_` prefix) does not exist in the symbol table. On Windows PE, `__imp_XYZ` symbols are thunks that point to the actual imported function/variable `XYZ`. This is an internal linker consistency error: the PE file declared an import thunk without a corresponding definition.

Source

Thrown at src/cmd/link/internal/loadpe/ldpe.go:828

}

// LookupBaseFromImport examines the symbol "s" to see if it
// corresponds to an import symbol (name of the form "__imp_XYZ") and
// if so, it looks up the underlying target of the import symbol and
// returns it. An error is returned if the symbol is of the form
// "__imp_XYZ" but no XYZ can be found.
func LookupBaseFromImport(s loader.Sym, ldr *loader.Loader, arch *sys.Arch) (loader.Sym, error) {
	sname := ldr.SymName(s)
	if !strings.HasPrefix(sname, "__imp_") {
		return 0, nil
	}
	basename := sname[len("__imp_"):]
	if arch.Family == sys.I386 && basename[0] == '_' {
		basename = basename[1:] // _Name => Name
	}
	isym := ldr.Lookup(basename, 0)
	if isym == 0 {
		return 0, fmt.Errorf("internal error: import symbol %q with no underlying sym", sname)
	}
	return isym, nil
}

View on GitHub (pinned to b6b368adc5)

Solutions

Ensure all required import libraries and DLL dependencies are available to the linker — check that `-L` paths include directories with the needed .lib/.a files.
Clean the build cache and rebuild to eliminate stale object files: `go clean -cache && go build`.
Update Go to the latest version — symbol processing order bugs are fixed over time.
If linking C code via cgo, verify the C compiler can build the code standalone (without Go) to rule out missing symbol definitions.
File a Go bug with the symbol name from the error message and the build configuration, as the error text explicitly labels this an 'internal error'.

Example fix

# Ensure all import libraries are available and rebuild cleanly
go clean -cache
go build -v ./...

# If using cgo with specific libraries, ensure CGO_LDFLAGS includes them:
CGO_LDFLAGS="-L/path/to/libs -lmylib" go build ./...

Defensive patterns

Strategy: validation

Prevention

Ensure all import libraries referenced by cgo code are available in the linker search path.
Use go clean -cache before rebuilding after changing C dependencies.
Verify DLL imports match between .h declarations and .lib files.
Keep the i386 vs amd64 distinction clear — import symbol name mangling differs.

When it happens

Trigger: Fires in `LookupBaseFromImport` at ldpe.go:826-828 when `ldr.Lookup(basename, 0)` returns 0, meaning the symbol `XYZ` (after stripping `__imp_` and optionally a leading underscore on i386) was never created during symbol loading. The function is called during relocation processing for symbols that begin with `__imp_`.

Common situations: Linking against a Windows import library (.lib) that references DLL imports not actually linked into the final binary. Stale or mismatched .a/.lib files from a previous build where the underlying symbol was later removed or renamed. A bug in the Go linker's symbol processing order where `LookupBaseFromImport` is called before all symbols have been registered. Mixing 32-bit and 64-bit object files where the `_Name` -> `Name` mangling (i386 only) doesn't match what was expected.

Related errors

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