New Relic Python Agent

Common errors

• newrelic-admin: not found

  cause The `newrelic-admin` wrapper script is not found in the system's PATH, or the New Relic Python agent is not installed in the currently active Python environment.
  fix Ensure the New Relic Python agent is installed in your application's virtual environment or system-wide, and that the `newrelic-admin` script (usually in `bin/` or `Scripts/` within your Python environment) is accessible via your system's PATH. You might need to activate your virtual environment or use its direct path.

• NEWRELIC: ... - New Relic could not start because the newrelic-admin script was called from a Python installation that is different from the Python installation that is currently running.

  cause This error occurs when the Python interpreter running the application differs from the Python interpreter used to run the `newrelic-admin` script, often seen in environments with multiple Python versions or virtual environments.
  fix Ensure that the `newrelic-admin` script and your application are executed using the *same* Python installation and virtual environment. This might involve explicitly calling the `newrelic-admin` script from the correct virtual environment's `bin` directory, e.g., `/path/to/venv/bin/newrelic-admin run-program your_app.py`.

• Initialization failed: Configuration has already been done against differing configuration file or environment.

  cause The New Relic Python agent's `newrelic.agent.initialize()` function was called multiple times with conflicting configuration parameters (different config files or environments), or conflicting environment variables/server-side configurations are present.
  fix Initialize the agent only once at the very beginning of your application's startup. Ensure consistency in configuration by using a single method (config file, environment variables, or `newrelic.agent.initialize()`) and avoiding conflicting settings across these methods. Environment variables override agent defaults, the config file overrides environment variables, and server-side config overrides the config file.

• ERROR - No license key was set in agent configuration.

  cause The New Relic Python agent cannot connect to the collector because the `license_key` is missing from the `newrelic.ini` configuration file or the `NEW_RELIC_LICENSE_KEY` environment variable is not set.
  fix Provide your New Relic license key either in the `license_key` setting within your `newrelic.ini` file or by setting the `NEW_RELIC_LICENSE_KEY` environment variable before your application starts.

• Python agent not reporting handled exceptions

  cause By default, the New Relic Python agent only reports *unhandled* exceptions that cause a transaction to end. Explicitly caught exceptions are not reported unless specifically instructed.
  fix To report handled exceptions, use `newrelic.agent.notice_error()` or `newrelic.agent.record_exception()` within your `except` blocks. These functions allow you to explicitly send exception details to New Relic APM.

Warnings

• breaking initialize() must be called before ALL other imports. Placing it after framework or library imports silently disables instrumentation — no exception is raised, agent appears to load but instruments nothing.
  Fix: Use newrelic-admin run-program wrapper, or place initialize() as the first two lines of your entry point before any other import.
• breaking Cross Application Tracing (CAT) fully removed in v12.0.0. Was deprecated since v7.0.0. Old tutorials and LLM-generated code using cross_application_tracer config keys will silently do nothing.
  Fix: Use Distributed Tracing (DT) instead. Remove cross_application_tracer settings from newrelic.ini.
• breaking Python 3.8 support dropped in v12.0.0 (Python 3.8 EOL was Oct 2024).
  Fix: Pin to newrelic<12.0.0 if still on Python 3.8, or upgrade Python.
• deprecated aioredis instrumentation deprecated. The aioredis package itself is abandoned. New Relic will remove this instrumentation in a future release.
  Fix: Use redis>=4.2 with redis.asyncio submodule. New Relic auto-instruments redis.asyncio.
• deprecated Configuring agent via WSGI environ dictionary is deprecated.
  Fix: Use environment variables (NEW_RELIC_LICENSE_KEY, NEW_RELIC_APP_NAME, etc.) or newrelic.ini config file.
• gotcha SSL certificates no longer bundled in v12.0.0. Environments without system CA certs (minimal Docker images) will fail to connect to New Relic.
  Fix: pip install newrelic[certificates]
• breaking New Relic agent initialization failed because the specified configuration file (e.g., 'newrelic.ini') could not be found or was inaccessible.
  Fix: Ensure the configuration file is present in the current working directory, specified by an absolute path, or use environment variables for configuration (NEW_RELIC_LICENSE_KEY, NEW_RELIC_APP_NAME, etc.) or a newrelic.ini config file managed by the deployment.
• breaking Calling `newrelic.agent.initialize(config_file)` requires the specified configuration file to exist and be accessible at the provided path. If the file is not found or cannot be read, a `newrelic.api.exceptions.ConfigurationError` will be raised.
  Fix: Ensure the 'newrelic.ini' configuration file is present in the application's working directory, or provide its absolute path to `newrelic.agent.initialize()`.

Install

• pip install newrelic Python (agent)
• newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini Generate config file
• pip install newrelic[certificates] Python (with bundled SSL certs, required in v12+)

Imports

• agent initialize
  wrong:

  from fastapi import FastAPI
  import newrelic.agent
  newrelic.agent.initialize('newrelic.ini')  # too late — FastAPI already imported

  correct:

  import newrelic.agent
  newrelic.agent.initialize('newrelic.ini')  # MUST be first lines before any framework imports

  initialize() must be called before ALL other library imports. Placing it after framework imports silently disables instrumentation with no error.
• CLI runner (recommended)
  wrong:

  gunicorn myapp.wsgi  # agent never loaded

  correct:

  NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn myapp.wsgi

  newrelic-admin run-program is the safest init method — handles import ordering automatically.

Quickstart

Agent initialization patterns. CLI wrapper is preferred. Manual init requires initialize() before all other imports.

# Option 1: CLI wrapper (recommended — handles ordering automatically)
# NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn myapp.wsgi

# Option 2: Manual init — must be absolute first lines of entry point
import newrelic.agent
newrelic.agent.initialize('newrelic.ini')

# Framework imports AFTER initialize()
from fastapi import FastAPI
app = FastAPI()