What causes "Error: Fail to PAL_InitializeDLL\n" in dotnet/runtime?

Build and use the shim-collector from the same CoreCLR artifacts tree as the runtime that hosts it.

Error: Fail to PAL_InitializeDLL\n

Error message

Error: Fail to PAL_InitializeDLL\n

What it means

The SuperPMI shim-collector is a replacement JIT DLL loaded by CoreCLR to record method contexts during compilation. On unix its InitializeShim (called from DllMain DLL_PROCESS_ATTACH) sets PAL_INITIALIZE_REGISTER_SIGNALS and calls PAL_InitializeDLL to set up the in-process PAL. If that returns non-zero the shim cannot function and calls exit(1), killing the host process at JIT-startup time.

Source

Thrown at src/coreclr/tools/superpmi/superpmi-shim-collector/superpmi-shim-collector.cpp:108

    if (g_collectionFilter != nullptr)
    {
        fprintf(stderr, "*** SPMI filter '%s'\n", g_collectionFilter);
    }
}

void InitializeShim()
{
    if (g_initialized)
    {
        return;
    }

#ifdef HOST_UNIX
    // Register signal handlers for the shim so we can handle committing collections on JIT segfaults.
    PAL_SetInitializeDLLFlags(PAL_INITIALIZE_REGISTER_SIGNALS);
    if (0 != PAL_InitializeDLL())
    {
        fprintf(stderr, "Error: Fail to PAL_InitializeDLL\n");
        exit(1);
    }
#endif // HOST_UNIX

#ifdef HOST_WINDOWS
    // Assertions will be sent to stderr instead of a pop-up dialog.
    _CrtSetReportMode(_CRT_ASSERT, _CRTDBG_MODE_FILE);
    _CrtSetReportFile(_CRT_ASSERT, _CRTDBG_FILE_STDERR);
#endif // HOST_WINDOWS

    g_initialized = true;
}

extern "C"
#ifdef HOST_UNIX
    DLLEXPORT // For Win32 PAL LoadLibrary emulation
#endif
        BOOL

View on GitHub (pinned to 60108ba66e)

Solutions

Build and use the shim-collector from the same CoreCLR artifacts tree as the runtime that hosts it.
Deploy all sibling runtime/PAL files alongside superpmi-shim-collector.so in the directory named by SuperPMIShimPath.
Verify the target arch matches (file superpmi-shim-collector.so) and that the host runtime is the same arch.
Run with DOTNET_DiagnosticPorts= or under strace to see which PAL dependency/fails during DLL_PROCESS_ATTACH.

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
# Validate the shim-collector is co-located with its PAL runtime siblings.
set -euo pipefail
DIR="$(dirname "${DOTNET_JITPATH:-superpmi-shim-collector.so}")"
file "$DIR/superpmi-shim-collector.so" | grep -qi "$(uname -m)" || { echo arch; exit 1; }
ldd "$DIR/superpmi-shim-collector.so" 2>/dev/null | grep -q 'not found' && { echo missing; exit 1; }

Prevention

Build and deploy the shim from the same CoreCLR artifacts tree as the host runtime.
Always keep PAL/runtime sibling files next to the shim .so.
Verify arch/OS match before enabling the collector.
strace the host at JIT load time to catch the first failing PAL syscall early.

When it happens

Trigger: Loading superpmi-shim-collector via DOTNET_JitPath / SuperPMIShimPath on unix when the PAL cannot initialize: missing runtime PAL modules next to the shim, mismatched CoreCLR build vs shim build, signal-handler registration blocked, or running under a sandbox that blocks the syscalls PAL needs.

Common situations: Pointing DOTNET_JitPath at a shim built for a different .NET version/arch; deploying only the shim DLL without its libpal/runtime siblings; enabling the collector in a restricted container; stale build artifacts after switching git branches.

Related errors

AI-assisted analysis of dotnet/runtime@60108ba66e (2026-08-10). Data as JSON: /api/errors/bc846958589c1b05. Report an issue: GitHub.