elfLink Error Codes and Linker Diagnostic Catalog

The elfLink subsystem is nvlink's internal library for loading, compiling, and linking device code modules. It wraps libnvvm for NVVM IR compilation, manages cubin/fatbinary extraction, and interfaces with the linker library (libnvvm.so). When any of these operations fail, elfLink returns an integer error code in the range 0--13. The function sub_4BC270 at 0x4BC270 translates these codes into human-readable strings via a lookup table at off_1D489E0.

Beyond the elfLink subsystem's 14 return codes, nvlink emits over 100 distinct user-facing diagnostic messages through the diag_emit (sub_467460) pipeline. This page catalogs every error string, maps each to its source function and triggering conditions, and provides user-facing fix suggestions.

Part 1: elfLink Error Code Table

The symbolic names above are inferred from the string content; the binary uses raw integer constants.

Lookup Function

// sub_4BC270 at 0x4BC270
// Table: off_1D489E0 -- 14 const char* entries (codes 0..13)
const char *elflink_error_string(unsigned int code)
{
    if (code <= 13)
        return error_table[code];   // off_1D489E0[code]
    return "elfLink: unexpected error";
}

The function is called from five sites in the binary:

Detailed Error Code Reference

Code 0 -- Success

No error. Returned when module loading, compilation, or linking completes without failure. Never passed to sub_4BC270 in practice.

Code 1 -- Internal Error

String: elfLink internal error (0x1D4883F)

Trigger: Returned by sub_4BDAC0 (host-ELF cubin extraction at 0x4BDAC0) and sub_4BDAF0 (host-ELF iterator at 0x4BDAF0) when the underlying ELF parser (sub_487C20, sub_487E10) returns an unrecognized status code (value > 2). Also returned by sub_4BC290 (library initialization at 0x4BC290) when the top-level context pointer is null or when nvvmCreateProgram fails. In the LTO compilation path (sub_4BC6F0), returned when nvvmGetProgramLog API calls fail.

Diagnosis: This is a catch-all for unexpected internal states. The input file may be corrupt, or an internal invariant was violated. Check that input object files are valid ELF. If the error persists with known-good inputs, it indicates a linker bug.

User fix: Verify input files with readelf -h to confirm valid ELF headers. Recompile inputs with the same toolkit version as nvlink.

Code 2 -- Cubin Error

String: elfLink error on cubin (0x1D48856)

Trigger: Produced when cubin extraction from a host ELF fails. The secondary table dword_1D48A50 maps parser status 1 to elfLink code 2. The parser returns status 1 when it encounters a malformed cubin section inside a host object file.

Diagnosis: The input .o file contains embedded device code (in .nv_fatbin or similar sections) that could not be parsed as a valid cubin. Recompile the source with the same toolkit version as nvlink.

User fix: Recompile the failing source file. If the file was produced by an older CUDA toolkit, upgrade the compilation to match the linker version.

Code 3 -- Fatbinary Error

String: elfLink fatbinary error (0x1D4886D)

Trigger: Produced when fatbinary extraction or decompression fails. The secondary table maps parser status 2 to elfLink code 3. This covers failures in the fatbinary header parsing, unsupported compression formats, or truncated fatbinary data.

Diagnosis: The fatbinary container embedded in the host object is invalid. Verify that the input was compiled with a compatible nvcc version. Truncated files (e.g., from interrupted builds) commonly produce this error.

User fix: Rebuild from scratch (make clean && make). Check for filesystem corruption or incomplete file copies.

Code 4 -- Incompatible Code (Memory Error)

String: elfLink memory error (0x1D48885)

Special handling: Code 4 receives unique treatment in sub_4297B0 -- instead of passing through sub_4BC270, the handler constructs a custom message by prepending a descriptive prefix (loaded from xmmword_1D34750 / xmmword_1D34760) and appending " code in <filename>". This produces a user-facing message like "elfLink found incompatible code in foo.o" rather than the generic table string. The same custom-message logic is duplicated in sub_42A2D0 for the host-ELF iteration path.

Trigger: Returned by sub_4BD0A0 (NVVM IR compilation driver at 0x4BD0A0) when the compilation pipeline fails at any stage: target architecture setup (sub_4CE2F0), debug mode configuration (sub_4CE380), 64-bit mode configuration (sub_4CE640), module addition (sub_4CE070), or final compilation (sub_4CE8C0). Also returned by sub_4BD240 (cubin post-processing at 0x4BD240) when ABI validation fails (-m32/-m64 mismatch) or when the cubin bytecode extractor (sub_4BE350) fails.

Diagnosis: Usually indicates a toolkit version mismatch. The cubin or NVVM IR module was compiled with options incompatible with the current link target. Check that all input objects target the same sm_ architecture and address size (32-bit vs 64-bit).

User fix: Ensure all .o files were compiled with the same -arch=sm_XX and -m64/-m32 flags. Check nvcc --version matches the nvlink version.

Code 5 -- JIT Compile Failed

String: elfLink JIT compile failed (0x1D4889A)

Trigger: Returned by sub_4BD0A0 when sub_4CE8C0 (the NVVM compilation call) returns a failure status other than 3 (which maps to code 7 instead). Also returned by sub_4BD240 when ABI checks fail (-m32/-m64 validation against sub_4CE3E0), or when a pass-through option string is rejected.

Diagnosis: The embedded NVVM IR or PTX could not be compiled to SASS for the target architecture. Check that the source was compiled for a compatible compute_ capability. If -dlto is in use, verify that all LTO objects were compiled with the same major CUDA toolkit version.

User fix: Verify the compute_ and sm_ targets are compatible. With LTO (-dlto), all objects must use the same CUDA toolkit major version.

Code 6 -- JIT Link Failed

String: elfLink JIT link failed (0x1D488B5)

Trigger: This code is only reachable through the error table. In the analyzed binary, no producer was found that explicitly returns 6. It is reserved for the case where the libnvvm link step (post-compilation module merging) fails, as distinct from compilation failure.

Diagnosis: If encountered, it means the NVVM linker was unable to merge compiled modules. This can happen when symbol visibility or linkage conflicts prevent merging.

User fix: Ensure that device-side extern declarations match across translation units. Check for conflicting function prototypes in device code headers.

Code 7 -- NVVM Error (Unresolved References)

String: elfLink nvvm error (0x1D488CD)

Special handling: Code 7 receives unique treatment parallel to code 4. In sub_4297B0, sub_42A2D0, and sub_42AF40, when the error code is 7 the handler checks byte_2A5F298 (the -lto-allow-unresolved flag at 0x2A5F298) and whether the filename contains "cudadevrt". If the flag is set or the input is libcudadevrt, the error is silently suppressed. Otherwise, a fatal diagnostic is emitted via descriptor unk_2A5B660:

nvvm IR for arch <target_arch> not found in <filename>

Trigger: Returned by sub_4BD0A0 when sub_4CE8C0 returns status 3, indicating that the NVVM compilation produced NVVM IR output (not SASS) -- meaning the module contains unresolved references that require a subsequent link step. This is expected for LTO intermediate objects and libcudadevrt.

Diagnosis: Typically not a true error. It indicates the module contains NVVM IR that cannot be finalized to SASS in isolation because it has unresolved references. When linking with -dlto, this is normal for all LTO input objects. It becomes a user-visible error only when encountered during non-LTO linking without -lto-allow-unresolved.

User fix: If you see this error, add -dlto to enable LTO linking. For libraries containing device runtime code, this is expected behavior.

Code 8 -- Cubin Not Relocatable

String: elfLink error cubin not relocatable (0x1D488E0)

Trigger: Returned by sub_4BD240 (cubin post-processing at 0x4BD240) when the cubin extraction via sub_4BE350 fails and the resulting context indicates no compilation output was produced (the compilation output pointer at offset +16 of the context is null). This means the cubin was compiled without relocatable device code (-rdc / -dc), making it unlinkable.

Diagnosis: The input cubin was compiled as a standalone (whole-program) object without separate compilation. Recompile with nvcc -dc (device code compilation) to produce relocatable device objects.

User fix: Add -dc (or equivalently -rdc=true) to the nvcc compile command. For static libraries, ensure they were built with -rdc=true.

Code 9 -- Cubin Not Compatible

String: elfLink error cubin not compatible (0x1D48908)

Trigger: Produced during cubin validation when the object's ELF metadata does not match the link-time target. This covers ABI version mismatches, size mismatches (32-bit vs 64-bit), and general compatibility flags that prevent linking.

Diagnosis: The input cubin was compiled with an incompatible ABI version or addressing mode. Check the nvcc version used to compile each input. The linker emits more specific diagnostics before this error:

• "Input file '%s' abi does not match" (0x1D34C68)
• "Input file '%s' size does not match target '%s'" (0x1D34C90)
• "Input file '%s' ABI version '%u' is incompatible with target ABI version '%u'" (0x1D34CF0)

User fix: Recompile all objects with the same toolkit version and matching address-size flags.

Code 10 -- Architecture Not Compatible

String: elfLink cubin arch not compatible (0x1D48930)

Trigger: Returned by sub_4BC290 (library initialization at 0x4BC290) when libnvvm.so cannot be loaded (the dlopen handle is null) or when the __nvvmHandle or nvvmCreateProgram symbols cannot be resolved via dlsym. Also returned by sub_4BC4A0 when similar symbol resolution failures occur for __nvvmHandle during the add-module call. In the LTO compilation path (sub_4BC6F0), returned when nvvmGetCompiledResult symbol lookup fails.

Diagnosis: Despite the name suggesting architecture incompatibility, this code primarily means the linker library infrastructure is unavailable. The libnvvm.so library could not be loaded or is from an incompatible toolkit version.

User fix: Verify that the CUDA toolkit installation is complete and that libnvvm.so is on the library search path (set via --libnvvm-path or the toolkit's lib64/ directory). Check LD_LIBRARY_PATH if needed.

Code 11 -- Linker Library Load Error

String: elfLink linker library load error (0x1D48958)

Trigger: Returned by sub_4BC4A0 (the add-module-to-program call at 0x4BC4A0) when the __nvvmHandle callback returns a non-null function pointer but calling that function with the module data returns a non-zero status. This means libnvvm.so was loaded successfully but rejected the specific module being added.

Diagnosis: The libnvvm runtime rejected the NVVM IR module. The module may be in an unsupported bitcode format version, or contain constructs not supported by the installed libnvvm.

User fix: Ensure that all input objects were compiled with the same CUDA toolkit version as the nvlink binary. Check nvcc --version and nvlink --version output.

Code 12 -- Incompatible Formats

String: elfLink error incompatible formats (0x1D48980)

Trigger: This code is reachable through the error table but no direct producer was identified in the analyzed call paths. It is reserved for cases where the input module format (cubin vs PTX vs NVVM IR) is incompatible with the requested link operation.

Diagnosis: The linker encountered a module in a format it cannot process in the current mode. For example, attempting to link a Mercury (capmerc) object in a CUDA-only link, or mixing incompatible ELF object formats.

User fix: Ensure all inputs are of the same format type. Do not mix Mercury objects with standard CUDA objects unless the linker is configured for Mercury mode.

Code 13 -- Finalization Failed

String: elfLink error finalization failed (0x1D489A8)

Trigger: This code maps to failures in the finalization (off-target to on-target compilation) step of the pipeline.

Diagnosis: The finalizer could not convert the intermediate representation to native SASS for the target architecture. This typically occurs during forward-compatibility finalization when the input cubin targets a different SM architecture. See also the separate "Internal FNLZR error '%s'" diagnostic (0x1D34F74) which provides more detail.

User fix: Ensure the target architecture (-arch) matches the sm_ target that inputs were compiled for. If using forward compatibility, verify the toolkit supports the target.

Error Dispatch Logic

The generic error handler sub_4297B0 at 0x4297B0 implements a three-way dispatch:

sub_4297B0(error_code, filename):
    if error_code == 0:
        return                          // success, nothing to report
    if error_code == 7:
        if lto_allow_unresolved or "cudadevrt" in filename:
            return                      // silently suppress
        fatal("nvvm IR for arch %s not found in %s", target_arch, filename)
    if error_code == 4:
        msg = "elfLink found incompatible code in " + filename
        fatal(msg)
    else:
        msg = elflink_error_string(error_code)   // sub_4BC270
        fatal(msg)

The same dispatch logic is replicated in sub_42A2D0 (host-ELF extraction path), which additionally handles the host-ELF iterator loop (sub_4BDAF0) -- calling the dispatch for each extracted cubin.

All fatal diagnostics go through sub_467460, which formats the message with the "error " severity prefix and writes to stderr. When --Werror is active, warnings are promoted to the "error* " level.

Part 2: Broader Diagnostic Message Catalog

Beyond the 14 elfLink error codes, nvlink emits a comprehensive set of user-facing diagnostics during linking. These are organized by severity and category.

Severity Levels

The diagnostic system at 0x1D3C660 defines six severity levels:

Category 1: Input File Errors

Category 2: Output File Errors

Category 3: Architecture and Compatibility Errors

Category 4: Symbol Resolution Errors

Category 5: Resource Limit Errors

Category 6: CLI Option Errors

Category 7: LTO-Specific Errors

Category 8: Warning-Level Diagnostics

Category 9: Internal Fatal Errors

These indicate linker bugs or unexpected states. They are routed through descriptor unk_2A5B670 (severity 6, fatal) or unk_2A5B990 (severity 6, internal assertion):

Category 10: External Tool Errors

Warning Suppression Flags

Several CLI options control diagnostic emission:

Error Flow Architecture

Input Processing (sub_42AF40 / sub_42A2D0)
    |
    +-- sub_4BD0A0  (NVVM IR compilation)    --> codes 0, 5, 7
    +-- sub_4BD240  (cubin post-processing)  --> codes 0, 1, 5, 8
    +-- sub_4BDAC0  (host-ELF extraction)    --> codes 0, 1, 2, 3
    +-- sub_4BDAF0  (host-ELF iteration)     --> codes 0, 1, 2, 3
    |
    v
sub_4297B0  (generic error dispatch)
    |
    +-- code 0:  no-op
    +-- code 4:  custom "elfLink found incompatible code in <file>" message
    +-- code 7:  conditional suppress (cudadevrt or -lto-allow-unresolved) or arch-specific fatal
    +-- other:   sub_4BC270(code) --> error string --> sub_467460 (fatal via unk_2A5B670)

Library Loading (main / sub_427A10)
    |
    +-- sub_4BC470  (dlopen libnvvm.so)      --> sub_4BC290 --> codes 0, 1, 10
    +-- sub_4BC4A0  (add module to program)  --> codes 0, 10, 11
    |
    v
    sub_4BC270(code) --> error string --> sub_467460 (fatal via unk_2A5B670)

LTO Compilation (sub_4BC6F0)
    |
    +-- nvvmCompileProgram via dlsym         --> code 8 (log + compile error)
    +-- nvvmGetProgramLog                    --> code 1 (API failure)
    +-- nvvmGetCompiledResult                --> code 10 (symbol lookup failure)
    |
    v
    Returns raw code to caller for sub_4BC270 translation

Split Compilation (main, thread pool)
    |
    +-- sub_43FDB0 / sub_43FF50             --> "Call to ptxjit failed"
    +-- sub_4264B0  (worker function)        --> per-item error codes
    +-- sub_4297B0  (per-result dispatch)    --> <lto ptx> as filename
    |
    v
    Per-item errors aggregated; fatal on first failure

ELF Merge + Layout + Relocate + Finalize (main phases)
    |
    +-- sub_439830  (merge)                  --> via unk_2A5B990 internal assertions
    +-- sub_469D60  (layout)                 --> resource limits (unk_2A5BA60..BA80)
    +-- sub_445000  (relocate)               --> undef refs, resource limits, section errors
    +-- sub_4475B0  (finalize / output)      --> write errors (unk_2A5B710)

Key Implementation Details

Secondary mapping table (dword_1D48A50): Functions sub_4BDAC0, sub_4BDAF0, and sub_4BDB30 use a 3-entry mapping table at 0x1D48A50 to convert their internal parser return codes (0, 1, 2) into elfLink codes (0, 2, 3). Values > 2 map to code 1 (internal error).

setjmp/longjmp error recovery: Several elfLink functions (sub_4BC290, sub_4BC4A0, sub_4BD240) use setjmp/longjmp for non-local error recovery. This allows deep call stacks within libnvvm to unwind cleanly back to the elfLink entry point. The longjmp path always returns code 1 (internal error), protecting the linker from crashes inside the dynamically loaded libnvvm.

Code 7 suppression logic: The NVVM error code (7) is the only error code with conditional suppression. The flag byte_2A5F298 (-lto-allow-unresolved) and the filename check for "cudadevrt" together determine whether the error is fatal or silently ignored. This allows libcudadevrt's NVVM IR to pass through the non-LTO path without aborting. The check is performed identically in three functions: sub_4297B0, sub_42A2D0, and sub_42AF40.

Code 4 custom message construction: Rather than using the generic table string, code 4 constructs a message from two SSE-loaded 16-byte constants (xmmword_1D34750, xmmword_1D34760) forming the prefix "elfLink found incompatible", followed by " code in " and the filename. This provides file-specific context that the generic string lacks. The 42-byte allocation (strlen(filename) + 42) accounts for the 33-byte prefix plus " code in " (9 bytes). This construction is duplicated in sub_42A2D0's iterator loop.

Multiple errors aggregation: The string "Multiple errors:\n" at 0x1D486CE indicates nvlink can aggregate multiple NVVM errors into a single diagnostic. The nvvmGetErrorString function (0x1D487F1) is resolved via dlsym to retrieve libnvvm-specific error details.

Descriptor unk_2A5B990 dominance: The internal-assertion descriptor unk_2A5B990 accounts for 230 of the 380+ total diag_emit call sites. It serves as the universal internal-error descriptor (always fatal, severity 6). Every call site passes a literal string describing the violated invariant. 40+ unique assertion messages have been cataloged; see Error Reporting for the complete list.

Complete String Address Index

All error-related strings confirmed in nvlink_strings.json, organized by address:

Cross-References

Internal (nvlink wiki):

• Error Reporting -- diag_emit (sub_467460) diagnostic pipeline with the complete 88-descriptor catalog and 40+ internal assertion messages
• LTO Overview -- LTO pipeline context where elfLink codes 5--7 arise from NVVM IR compilation
• libnvvm Integration -- dlsym/dlopen lifecycle for libnvvm.so loading (codes 10--11)
• Split Compilation -- LTO split-compile path where elfLink errors propagate from parallel PTX-to-SASS workers
• Fatbin Extraction -- Fatbinary parsing path where code 3 (fatbin error) originates
• Cubin Loading -- Input cubin validation where codes 8 (not relocatable) and 9 (not compatible) originate
• Architecture Compatibility -- Arch mismatch checks that produce code 10 (arch not compatible)
• Pipeline Entry -- main() top-level error handling that translates elfLink codes to user diagnostics
• Symbol Resolution -- Symbol merge/resolve logic that produces multiple-definition and undefined-reference errors
• Dead Code Elimination -- DCE callgraph logic that can trigger "reference to deleted symbol" assertions

Confidence Assessment