Add DOTNET_DbgCreateDumpToolPath to override createdump directory (NativeAOT only) #122989

Copilot · 2026-01-07T20:32:07Z

Description

Adds DOTNET_DbgCreateDumpToolPath environment variable to allow specifying a directory path where the createdump tool is located. In scenarios where createdump is not shipped with the NativeAOT runtime, users can now provide their own dump generation tool.

Note: This environment variable is only supported in NativeAOT applications and is ignored otherwise (not in other runtime configurations).

Implementation

Modified PalCreateDumpInitialize() to check DOTNET_DbgCreateDumpToolPath for a directory path
The runtime concatenates the directory path with "createdump" following the same pattern as the default behavior
No file validation during initialization (aligned with commit c507305 which removed stat checks)
Follows existing environment variable pattern using RhConfig::Environment::TryGetStringValue()
Uses safe string handling with proper null-termination and buffer management
Maintains backward compatibility: falls back to default behavior when not set

Usage

export DOTNET_DbgEnableMiniDump=1
export DOTNET_DbgCreateDumpToolPath=/path/to/directory
./myapp

The runtime will look for /path/to/directory/createdump

Customer Impact

Customers deploying NativeAOT in environments without createdump (custom distributions, minimal containers, embedded systems) currently cannot generate crash dumps. This prevents critical debugging in production scenarios.

Regression

No. This is a new opt-in feature with no impact on existing behavior. Only affects NativeAOT applications.

Testing

NativeAOT runtime build verification (clr.nativeaotruntime)
Code follows existing patterns for environment variable handling and memory management
Documentation updated with usage examples and NativeAOT-only clarification using "ignored otherwise" wording to avoid ambiguity since NativeAOT uses a stripped-down version of CoreCLR
Safe string handling verified

Risk

Low. New environment variable only used when explicitly set. Code path follows existing directory concatenation pattern used for default createdump lookup. No changes to existing dump generation logic. NativeAOT only, so no impact on other runtime configurations.

Original prompt

Using a new environment variable DOTNET_DbgCreateDumpToolPath, add the ability to override where we look for the createdump tool in the PalCreateDumpInitialize in PalCreateDump.cpp. In some scenarios we do not ship createdump and we should make it easier to 'bring your own' should one decide they need a dump.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: steveisok <[email protected]>

jkotas · 2026-01-09T05:16:51Z

src/coreclr/nativeaot/Runtime/unix/PalCreateDump.cpp

-        if (dladdr((void*)&PalCreateDumpInitialize, &info) == 0)
+        char* program = nullptr;
+
+        // Check if user provided a custom path to createdump tool


Does this need to be supported in regular CoreCLR copy of this logic as well?

My understanding is that the coreclr path will have createdump next to it. Certainly does not hurt to have the override there as well.

@noahfalk @hoyosjs thoughts?

I think adding the env var on CoreCLR might just create a can of worms we'd prefer not to open. Coreclr dump collection needs DAC to enumerate the right memory and the DAC<->runtime are tightly coupled. The env var makes it much easier for folks to redirect dump collection to an incompatible collector. For example in the CI scenario anyone redirecting create dump for NativeAOT apps might inadvertently be retargetting all their CoreCLR apps too without meaning to do that.

Do we have an existing naming convention to specify that an env var only applies to NativeAOT? I also think it would be OK if we left the name alone and just deliberately ignored the env var on CoreCLR.

I'm not aware of any nativeaot specific naming convention. If there isn't, I'd rather not start one and just document this does not apply to coreclr.

@copilot please adjust reading the DbgCreateDumpToolPath to only extract the path. The behavior to detect if the file exists changed in another commit. Additionally, DbgCreateDumpToolPath is the path to where the createdump tool lives, not the full path to an executable named something arbitrary. Please make sure to read the path from the DbgCreateDumpToolPath environment variable and use that to concat in the way we do it by default. Finally, please make sure to update the documentation to indicate DbgCreateDumpToolPath works with NativeAOT only.

Do we have an existing naming convention to specify that an env var only applies to NativeAOT

We explicitly do not have a naming convention like that. We want NativeAOT to be as similar as possible to regular CoreCLR.

NativeAOT is not the only form-factor with this problem. Regular single file apps have the same problem (there is no createdump and DAC library for single file apps either). We have "solved" the problem for single file apps by supporting full dumps only. If you set DOTNET_DbgEnableMiniDump=1 for single file apps and your app crashes, you will see "Only full dumps are supported by single file apps. Change the dump type to full (DOTNET_DbgMiniDumpType=4)". It would be nice to be consistent across all single-file form factors.

@copilot are you able to create a follow up github issue that tracks making DOTNET_DbgEnableMiniDump and DOTNET_DbgMiniDumpType consistent across all single-file form factors?

I don't have the capability to create GitHub issues directly. However, here's a suggested issue description you can use:

Title: Make DOTNET_DbgEnableMiniDump and DOTNET_DbgMiniDumpType consistent across all single-file form factors

Description:
Currently, different single-file form factors handle dump generation inconsistently:

Regular single-file apps only support full dumps and show an error message if other dump types are requested

NativeAOT apps now support custom createdump paths via DOTNET_DbgCreateDumpToolPath

We should standardize the behavior across all single-file form factors to provide a consistent developer experience.

Area: Diagnostics/Dump Generation
Related PR: #[this PR number]

It would be nice to be consistent across all single-file form factors.

We could make NativeAOT less functional to increase the parity - require minidump type full and don't add this env var at all. Getting to higher levels of parity probably requires making the specialized dump collection logic an optional linkable component for NativeAOT and SingleFile which sounds out of scope for this PR.

Ok, we can leave this for a follow up

dotnet-policy-service · 2026-01-09T07:13:14Z

Tagging subscribers to this area: @steveisok, @dotnet/dotnet-diag
See info in area-owners.md if you want to be subscribed.

…dbgcreatdumptoolpath

… validation - Changed DbgCreateDumpToolPath to accept a directory path instead of full executable path - The runtime now concatenates the directory with "createdump" like the default behavior - Removed stat() validation as it was removed in commit c507305 - Updated documentation to clarify this is NativeAOT only and the variable accepts a directory path - Updated usage example to reflect the directory path usage Co-authored-by: steveisok <[email protected]>

- Initialize buffer with '\0' before using strncat - Use proper buffer size calculations in strncat calls to prevent buffer overruns - Ensures safe string concatenation following C string best practices Co-authored-by: steveisok <[email protected]>

- Calculate exact buffer size based on whether slash is needed - Follow same pattern as default code path using strncpy and strncat - More readable and maintainable code structure Co-authored-by: steveisok <[email protected]>

docs/design/coreclr/botr/xplat-minidump-generation.md

Changed "ignored in CoreCLR" to "ignored otherwise" since NativeAOT uses a stripped-down version of CoreCLR, making the original wording ambiguous. Co-authored-by: steveisok <[email protected]>

Copilot

Pull request overview

This pull request adds a new environment variable DOTNET_DbgCreateDumpToolPath to allow NativeAOT applications to specify a custom directory where the createdump tool is located. This addresses scenarios where createdump is not shipped with the NativeAOT runtime, enabling users to provide their own dump generation tool.

Changes:

Modified PalCreateDumpInitialize() to check for DOTNET_DbgCreateDumpToolPath environment variable and use it to locate createdump
Added if/else logic to support both custom path and default library-based path discovery
Updated documentation to describe the new environment variable and its NativeAOT-only support

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
src/coreclr/nativeaot/Runtime/unix/PalCreateDump.cpp	Adds environment variable check and custom path handling for createdump tool location with proper memory management and path concatenation logic
docs/design/coreclr/botr/xplat-minidump-generation.md	Documents the new DOTNET_DbgCreateDumpToolPath environment variable with usage examples and NativeAOT-only clarification

docs/design/coreclr/botr/xplat-minidump-generation.md

Co-authored-by: Copilot <[email protected]>

jkotas · 2026-01-13T05:16:15Z

docs/design/coreclr/botr/xplat-minidump-generation.md

 - `DOTNET_DbgEnableMiniDump`: if set to "1", enables this core dump generation. The default is NOT to generate a dump.
 - `DOTNET_DbgMiniDumpType`: See below. Default is "2" MiniDumpWithPrivateReadWriteMemory.
 - `DOTNET_DbgMiniDumpName`: if set, use as the template to create the dump path and file name. See "Dump name formatting" for how the dump name can be formatted. The default is _/tmp/coredump.%p_.
+- `DOTNET_DbgCreateDumpToolPath`: **(NativeAOT only)** if set, specifies the directory path where the createdump tool is located. The runtime will look for the createdump binary in this directory. This is useful in scenarios where createdump is not shipped with the runtime and you need to "bring your own" dump generation tool. This environment variable is only supported in NativeAOT applications and ignored otherwise.


This should be documented int the official docs: t https://learn.microsoft.com/en-us/dotnet/core/diagnostics/collect-dumps-crash

(We may want to do delete the env variable documentation here and just link to the official docs.)

The official docs should mention that this works in .NET 11+ only

Initial plan

5a1409b

Copilot AI assigned Copilot and steveisok Jan 7, 2026

Copilot started work on behalf of steveisok January 7, 2026 20:32 View session

Copilot AI and others added 3 commits January 7, 2026 20:54

Add DOTNET_DbgCreateDumpToolPath environment variable support

466f07f

Co-authored-by: steveisok <[email protected]>

Add documentation for DOTNET_DbgCreateDumpToolPath environment variable

be662d2

Co-authored-by: steveisok <[email protected]>

Add usage example for DOTNET_DbgCreateDumpToolPath

2870ba9

Co-authored-by: steveisok <[email protected]>

Copilot AI changed the title ~~[WIP] Add ability to override createdump tool path~~ Add DOTNET_DbgCreateDumpToolPath to override createdump location Jan 7, 2026

Copilot AI requested a review from steveisok January 7, 2026 21:07

Copilot finished work on behalf of steveisok January 7, 2026 21:07

jkotas reviewed Jan 9, 2026

View reviewed changes

jkotas added the area-Diagnostics-coreclr label Jan 9, 2026

Merge remote-tracking branch 'upstream/main' into copilot/add-dotnet-…

a56aadf

…dbgcreatdumptoolpath

Copilot started work on behalf of steveisok January 10, 2026 19:19 View session

Copilot AI and others added 3 commits January 10, 2026 19:26

Simplify string concatenation logic for better clarity

5d6a589

- Calculate exact buffer size based on whether slash is needed - Follow same pattern as default code path using strncpy and strncat - More readable and maintainable code structure Co-authored-by: steveisok <[email protected]>

Copilot AI changed the title ~~Add DOTNET_DbgCreateDumpToolPath to override createdump location~~ Add DOTNET_DbgCreateDumpToolPath to override createdump directory (NativeAOT only) Jan 10, 2026

Copilot finished work on behalf of steveisok January 10, 2026 19:30

jkotas reviewed Jan 11, 2026

View reviewed changes

docs/design/coreclr/botr/xplat-minidump-generation.md Outdated Show resolved Hide resolved

Copilot started work on behalf of steveisok January 12, 2026 21:21 View session

Update documentation wording to avoid ambiguity about CoreCLR

74fc3af

Changed "ignored in CoreCLR" to "ignored otherwise" since NativeAOT uses a stripped-down version of CoreCLR, making the original wording ambiguous. Co-authored-by: steveisok <[email protected]>

Copilot finished work on behalf of steveisok January 12, 2026 21:26

steveisok mentioned this pull request Jan 12, 2026

Make DOTNET_DbgEnableMiniDump and DOTNET_DbgMiniDumpType consistent across all single-file form factors #123102

Open

steveisok marked this pull request as ready for review January 12, 2026 21:30

steveisok requested a review from MichalStrehovsky as a code owner January 12, 2026 21:30

Copilot AI review requested due to automatic review settings January 12, 2026 21:30

Copilot started reviewing on behalf of steveisok January 12, 2026 21:31 View session

Copilot AI reviewed Jan 12, 2026

View reviewed changes

docs/design/coreclr/botr/xplat-minidump-generation.md Outdated Show resolved Hide resolved

docs/design/coreclr/botr/xplat-minidump-generation.md Outdated Show resolved Hide resolved

jkotas and others added 2 commits January 12, 2026 21:11

Update docs/design/coreclr/botr/xplat-minidump-generation.md

c1c10b0

Co-authored-by: Copilot <[email protected]>

Update docs/design/coreclr/botr/xplat-minidump-generation.md

12d8194

Co-authored-by: Copilot <[email protected]>

jkotas reviewed Jan 13, 2026

View reviewed changes

jkotas approved these changes Jan 13, 2026

View reviewed changes

Add DOTNET_DbgCreateDumpToolPath to override createdump directory (NativeAOT only) #122989

Are you sure you want to change the base?

Add DOTNET_DbgCreateDumpToolPath to override createdump directory (NativeAOT only) #122989

Conversation

Copilot AI commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Implementation

Usage

Customer Impact

Regression

Testing

Risk

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkotas Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dotnet-policy-service bot commented Jan 9, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Jan 7, 2026 •

edited

Loading

jkotas Jan 10, 2026 •

edited

Loading