dotnet/runtime · critical

BEGIN: coreclr_initialize failed - Error: 0x%08x

Error message

BEGIN: coreclr_initialize failed - Error: 0x%08x

What it means

Opening marker printed to stderr when the coreclr_initialize() call in run() returns a failing HRESULT (FAILED(result) is true). The host then dumps exe path, all runtime properties, managed assembly path, and arguments via logger.dump_details() before the matching END line. The 0x%08x is the raw CoreCLR HRESULT, which encodes the specific initialization failure reason.

Source

Thrown at src/coreclr/hosts/corerun/corerun.cpp:615

    }

#ifdef TARGET_WASM
    // install the pinvoke override callback to resolve p/invokes to statically linked libraries
    add_pinvoke_override();
#endif // TARGET_WASM

    int result;
    result = coreclr_init_func(
        exe_path_utf8.c_str(),
        "corerun",
        propertyCount,
        propertyKeys.data(),
        propertyValues.data(),
        &CurrentClrInstance,
        &CurrentAppDomainId);
    if (FAILED(result))
    {
        pal::fprintf(stderr, W("BEGIN: coreclr_initialize failed - Error: 0x%08x\n"), result);
        logger.dump_details();
        pal::fprintf(stderr, W("END: coreclr_initialize failed - Error: 0x%08x\n"), result);
        return -1;
    }

    if (coreclr_set_error_writer_func != nullptr)
    {
        coreclr_set_error_writer_func(nullptr);
    }

    int exit_code;
    {
        actions.before_execute_assembly(config.entry_assembly_fullpath);

        result = coreclr_execute_func(
            CurrentClrInstance,
            CurrentAppDomainId,
            config.entry_assembly_argc,

View on GitHub (pinned to 290d5ab72c)

Solutions

1. Read the HRESULT between BEGIN and END and decode it (e.g. 0x80070002 = ERROR_FILE_NOT_FOUND -> a TPA path is wrong).
2. Check the dumped 'Properties:' block, especially TRUSTED_PLATFORM_ASSEMBLIES, for missing/incorrect paths.
3. Confirm CORE_ROOT and CORE_LIBRARIES are set to directories that actually contain System.Private.CoreLib.dll and the rest of the BCL.
4. Remove or correct any -p user-defined properties and re-run; ensure the entry assembly exists and is a valid managed PE.
5. Set DOTNET_DIAGNOSTIC_PORTS / enable coreclr_set_error_writer output (already wired) to get the runtime's own diagnostic line.

Example fix

# before: TPA list is empty because CORE_ROOT has no DLLs
export CORE_ROOT=/empty
corerun App.dll
# after
export CORE_ROOT=/path/to/shared/Microsoft.NETCore.App/8.0.x
corerun App.dll

# validate TPA / CORE_ROOT before running
test -n "$CORE_ROOT" || { echo 'CORE_ROOT unset'; exit 1; }
test -f "$CORE_ROOT/System.Private.CoreLib.dll" || { echo 'missing System.Private.CoreLib.dll'; exit 1; }
ls "$CORE_ROOT"/*.dll >/dev/null 2>&1 || { echo 'CORE_ROOT has no TPA dlls'; exit 1; }

When it happens

Trigger: coreclr_init_func() is invoked with exePath, 'corerun', propertyCount, keys/values (TRUSTED_PLATFORM_ASSEMBLIES, APP_PATHS, NATIVE_DLL_SEARCH_DIRECTORIES, user properties, HOST_PROPERTY_RUNTIME_CONTRACT), and the runtime refuses to start. Common HRESULTs include 0x80070002 (file not found), 0x80131700 (framework init failure), 0x80004005 (unspecified).

Common situations: TRUSTED_PLATFORM_ASSEMBLIES list missing or pointing at non-existent mscorlib/System.Private.CoreLib; APP_PATHS or NATIVE_DLL_SEARCH_DIRECTORIES wrong; a user-defined property (-p key=value) has an invalid value; the entry assembly path is inaccessible; bitness mismatch between host and TPA assemblies.

Related errors

• END: coreclr_initialize failed - Error: 0x%08x
• BEGIN: coreclr_execute_assembly failed - Error: 0x%08x
• END: coreclr_execute_assembly failed - Error: 0x%08x
• coreclr_shutdown_2 failed - Error: 0x%08x
• Export '%s' not found.

AI-assisted analysis of dotnet/runtime@290d5ab72c (2026-08-06). Data as JSON: /api/errors/559dab961708e72d. Report an issue: GitHub.