Your data. Anywhere you go.

New Relic for iOS or Android

Download on the App Store    Android App on Google play

New Relic Insights App for iOS

Download on the App Store

Learn more

Close icon

Relic Solution: .NET Core Agent Installation Issues - A Troubleshooting Guide


If you already see a logs folder in the directory where the .NET Core agent was extracted and new log files are generated inside that directory when you restart your .NET Core application, then the .NET Core agent is already correctly installed on your system and you can head over to <Troubleshooting With .NET Agent Log Files> to start digging in to the logs themselves.

The point of this post is to provide troubleshooting steps for common installation issues with the .NET Core agent in Windows or Linux environments. It is intended to make sure the agent is correctly configured to profile .NET Core applications on your system. At the end of this post you should see a logs folder with logs in it inside the directory where you extracted the .NET Core agent on your server, and new log files should be generated when you restart your application. The presence of these logs indicates that the agent is correctly “installed” on your system. There may be additional configuration required to get data reporting to your New Relic account, but that configuration is outside the scope of this post.

The first thing to note is that the .NET Core agent is not an “installed” application. It is a folder on your server which contains the agent files. You instruct the .NET Core Runtime to load these files into your application process by setting certain environment variables for the application’s environment.

If you used an .msi package with an installer GUI to put the agent on your Windows system, then you have likely installed the .NET Framework agent, instead of the .NET Core agent. If this is the case you will see “New Relic .NET Agent” in your Windows “Programs and Features” menu. The .NET Core agent will NOT show in “Programs and Features”. The .NET Core agent is distinct from the .NET Framework agent, so make sure you install the correct one. Instructions for installing the .NET Core agent in Windows can be found <at this link>.

There are four main areas of consideration when diagnosing installation issues in the .NET Core agent:

  1. Is the application supported by the .NET Core agent?
  2. Is the correct build of the agent present on the system?
  3. Are the environment variables being set correctly?
  4. Does the application have the correct permissions to access the agent folder and write to the logs folder?

Is the application supported by the .NET Core agent?

Official documentation on .NET Core agent compatibility requirements can be found <at this link>.

The following are the most common reasons that a .NET Core application would fail to meet the compatibility requirements:

The application is built on a .NET Core version lower than 2.0.

  • The .NET Core agent does not support applications built on .NET Core 1.0 or 1.1. .NET Core version 2.0 or higher is required for the agent to monitor your .NET Core application.

The .NET Core application targets the .NET Framework CLR.

  • Look at your application’s .csproj file (located in the root folder of your project) and check to see what the value of the <TargetFramework> attribute is. If the target framework is netcoreapp2.0, then the application is likely supported by the .NET Core agent. If the value is a .NET Framework version (such as net452), the application is not supported by the .NET Core agent. To monitor ASP.NET Core applications which target the .NET Framework, use the .NET Framework agent, version 8.1 or higher.

  • You may need to get a developer to look at the .csproj file for you if you don’t have access to it. Many times the .csproj file is not deployed to production with the application.

If your .NET Core application does not fall into either of the above categories, it is very likely that you WILL be able to monitor your application using the .NET Core agent.

Is the correct build of the agent present on the system?

Note: Make sure that you know the full path to the folder where the agent files were extracted on the server. This will be important when setting up your environment variables.

There are multiple builds of the .NET Core agent for use in Windows or Linux operating systems. Check the folder where you extracted the .NET Core agent and make sure you are using the correct build for your OS.

In the folder where you extracted the agent:

  • If you see the file NewRelic.Profiler.dll, then you have the Windows build of the agent on your system.
  • If you see the file, then you have the Linux build of the agent on your system.

If you need to change the build that is present on your system, you can download any of the available builds for the most recent version of the agent at <this link>.

Are the environment variables being set correctly?

Note: Please see the note at the end of this section for details on a common environment variable issue that affected agents versions prior to version 8.1 when used with a service manager.

There are a multitude ways to set environment variables for a given process on a given OS. The actual process of setting the variables is not the goal of this post, but rather to give you information about what you should expect to see when the variables are loaded correctly.

There are four environment variables that must be present in order for the .NET Core agent to attach to the application. Please note that having the variables present on the system is not enough, the variables must actually be loaded into the application’s host process. They are:





To check if these variables are being loaded into your application’s process, start the application on your server and follow the steps below:


Use Microsoft Process Explorer to inspect the environment of your application’s process. Instructions for doing this can be found <at this link>.


Identify the Process ID (PID) your application is running under and execute the following in a command prompt, replacing ***YOUR PID*** with the PID of your process.

xargs --null --max-args=1 < /proc/***YOUR PID***/environ | grep CORE

Special considerations when using a service manager (such as IIS as a reverse-proxy via the ASP.NET Core Module)

In older versions of the .NET Core agent (prior to version 8.1), the agent imbedded a reference to the CORECLR_NEWRELIC_HOME variable inside the CORECLR_PROFILER_PATH variable. When used with a service manager, this imbedded variable sometimes failed to expand correctly, resulting in an invalid file path.

This has since been corrected, but if your variables are still set to:





You should replace the imbedded variable with the full path to the profiler file.





Does the application have the correct permissions to access the agent folder and write to the logs folder?

In order for the agent to function properly, the application process must have read and write permissions to the directory where the .NET Core agent has been extracted. Note that the permissions required are for the user account that the application is running under, not the user you are logged into the OS as.

To troubleshoot if user permissions are the cause of agent installation issues, you may find it helpful to temporarily set very generous user permissions for all users on the system to the .NET Core agent folder. If this resolves the issue you know that user permissions are the problem and you can focus your troubleshooting efforts on identifying the correct user account for your application and granting the correct permissions for that user.

What Now?

If you’ve gone through all of the above steps and restarted your application (or issued a command-line iisreset, if applicable), you should now see a “logs” folder in the directory where the .NET Core agent was extracted, and that folder should contain current log files.

If you have logs, but still no data in the UI, head over to <Troubleshooting With .NET Agent Log Files> to start digging in to the logs themselves.

The presence of current logs in the logs folder indicates that the .NET Core agent is correctly configured on your system and able to profile/monitor .NET Core applications. This does not guarantee that the agent is configured correctly to send data to your New Relic account.

If you do not see log files or a logs folder after following this post, please reach out to New Relic support for more assistance, or create a new Explorer’s Hub forum post to ask the community.

Hope this helps!


APM .NET CORE 2.0 Installation Help
Net core agent doesn't work with IIS and AspNetCoreModule
How to setup New Relic for ASP.NET Core 2.1 website application hosted in Windows & IIS
Relic Solution: Troubleshooting With .NET Agent Log Files
Newrelic agent error
.net core agent problem on debian kestrel nginx
Can not setup agent with .net core app
2018 Review of Community Awesomeness