Troubleshooting SDK Errors

A list of all Node.js SDK runtime errors, their causes, and how to fix them.

E1011 - Provided key is invalid

Error Message

Can't load Hud, the provided key is invalid. Please provide a valid HUD_KEY.

Explanation
The SDK failed to initialize because the API key is missing, malformed, or unrecognized by the Hud backend.

Solution

  1. Ensure your API key is copied exactly from your Hud dashboard.
  2. Verify your secret management is correctly passing the key to your runtime.
  3. Log in to Hud to confirm the key is valid and associated with your project.

E1012 - Unsupported Node version

Error Message

Can't load Hud due to an unsupported Node.js version.

Explanation
Your application is running a Node.js version that isn't supported by the SDK.

Solution

  1. Check your Node.js version against the Support Matrix.
  2. Upgrade to a supported version if necessary.
  3. Restart your service after updating Node.js.

E1019 - API key not found

Error Message

API key not found. SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation
The SDK was started without an API key. Since the key is required for authentication, the SDK shuts down gracefully.

Solution

  1. Pass the API key as the first argument to initSession().
  2. Ensure your secrets setup is passing it correctly.

E1020 - Service name not found

Error Message

Service name parameter not found. SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation
The required serviceName parameter was missing during SDK setup.

Solution

  1. Provide aserviceName as the second argument to initSession().
  2. Check for typos or undefined values in your initialization code.

E1021 - HUD_ENABLE is false

Error Message

HUD_ENABLE is set to false. SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation
The SDK was intentionally disabled using the HUD_ENABLE=false environment variable.

Solution

  • No action is required unless this was unintentional.
  • To enable the SDK, set HUD_ENABLE=true in your environment or remove the variable entirely.

E1022 - Instrumented function limit exceeded

Error Message

SDK limit of instrumented functions exceeded. SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation
Your app exceeded the maximum number of functions Hud is allowed to instrument, to avoid performance issues.

Solution

  1. Reduce the number of instrumented functions, especially via includeModules.

E1023 - Pod memory limit too low

Error Message

Insufficient memory available. SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation
Hud requires a minimum memory threshold. If your container/pod doesn’t meet it, the SDK shuts down to avoid crashes.

Solution

  1. Increase memory limits in your container/pod spec (e.g., Kubernetes, Docker).
  2. Contact your platform team if limits are managed centrally.
  3. Restart the service after increasing memory.

E1024 - Debugger detected

Error Message

Did not load as debugger is attached.

Explanation
Hud detects when a debugger is attached and disables itself to avoid unintended behavior or security issues.

Solution

  1. Detach the debugger before launching your application.
  2. Avoid using debuggers in production environments.

E1025 - register() not called before initSession()

Error Message

Hud: register() was not called, or called after initSession() - please call register() before initSession() and run again. Your application continues normally without Hud.

Explanation
Hud requires register() to be called before initSession(). If it's missing or called too late, Hud will not initialize but your app will continue unaffected.

Solution

  1. Callregister() before initSession() – ideally at the very start of your main file.
  2. Ensureregister() is not conditionally skipped.
  3. Check for race conditions or async delays that may cause initSession() to run too early.

E1026 - No code has been mapped

Error Message

Hud: Warning - No code has been mapped so far. This probably means register() was called too late — after your code was already loaded. Move it to the top of your entry file to enable proper mapping. Your application continues normally without Hud data.

Explanation
Hud maps your code at runtime to collect meaningful performance and error data. If register() is called after most of your application has loaded, Hud misses the opportunity to map your code correctly.

Solution

  1. Callregister() at the very top of your main entry file, before importing or executing any other code.
  2. Alternatively, use Option A – Preferred: Preload with--require from the integration guide to ensure Hud is loaded before your application.
  3. Avoid placingregister() inside conditionals, functions, or asynchronous blocks.

E1027 - Some code files were loaded before register()

Error Message

Hud: Warning - <x> of your code files were imported before register(). This means Hud won’t track all of your functions. Please move register() call to an earlier location. To view the list of files use register(\{‘verbose’:true}). Your application continues normally, but with partial Hud data.

Explanation
Hud must be initialized before any user code is imported in order to map and monitor functions. If files are loaded before register() is called, Hud cannot retroactively instrument them, resulting in incomplete data collection.

Solution

  1. Move theregister() call to the very top of your application’s entry point, before importing any other modules.
  2. Useregister({ verbose: true }) to log which files were loaded too early and adjust your import order accordingly.
  3. Prefer Option A – Preload with--require from the installation guide to guarantee proper loading.
  4. Avoid placingregister() inside conditionals or deferred execution paths.

E1028 - Framework loaded before register()

Error Message

Hud: Warning - The framework(s): <framework_name> was imported before register(). This means Hud won’t track your framework invocations. Please move register() call to an earlier location. Your application continues normally, but with partial Hud data.

Explanation
Hud hooks into your framework (e.g., Express, Koa, Kafka) to monitor and correlate incoming requests with function behavior. If the framework is imported before register(), Hud cannot instrument it, resulting in missing framework level visibility.

Solution

  1. Move theregister() call to the very top of your entry file, before importing any framework like Express or Koa.
  2. Ensureregister() runs before any server setup logic.
  3. Prefer Option A – Preload with--require to guarantee Hud is initialized before your app

E1029 - Unsupported version of framework

Error Message

Hud: Warning - Unsupported version of framework(s): <framework_name>. This means Hud won’t track your framework invocations. Your application continues normally, but with partial Hud data. See the compatibility matrix for details: docs.hud.io/docs/hud-sdk-compatibility-matrix-for-node

Explanation
Hud supports specific versions of popular frameworks in order to trace and correlate incoming requests. If you're using an unsupported version, Hud cannot hook into the framework and will not record framework level data.

Solution

  1. Check your framework version (e.g., Express, NestJS).
  2. Refer to the compatibility matrix to verify support.
  3. If possible, upgrade or downgrade to a compatible version to restore full functionality.
  4. Chat with our support team or email us at [email protected] if you need help validating version compatibility or requesting support for a specific version.


E1030 - HTTP framework not supported

Error Message

Hud: Warning - HTTP framework <framework_name> is not supported. Your HTTP calls won’t be tracked. Your application continues normally, but with partial Hud data.See the compatibility matrix for details: docs.hud.io/docs/hud-sdk-compatibility-matrix-for-node

Explanation
Hud integrates with specific HTTP frameworks to monitor incoming requests. If your framework is not on the supported list, Hud cannot instrument it, and request-level data will be unavailable.

Solution

  1. Refer to the compatibility matrix to check supported frameworks.
  2. Consider switching to a supported framework if full HTTP visibility is important for your use case.
  3. Chat with our support team or email us at [email protected] if you need help validating framework compatibility or requesting support for a specific framework.


E1031 - Queue framework not supported

Error Message

Hud: Warning - Queue framework <framework_name> is not supported. Your Queue events won’t be tracked. Your application continues normally, but with partial Hud data.

Explanation
Hud integrates with specific Queue frameworks to monitor events processing. If your framework is not on the supported list, Hud cannot instrument it, and queue data will be unavailable.

Solution

  1. Move theregister() call to the top of your main entry file, before importing any queue framework.
  2. Ensureregister() is not conditionally delayed or wrapped in async logic.
  3. Use Option A – Preload with--require to ensure early initialization

E1032 - No function activity tracked

Error Message

Hud: Warning - Code mapped successfully, but no function activity was tracked. Make sure your service is running and actively handling requests.

Explanation
Hud successfully mapped your codebase but did not detect any runtime function invocations. This usually means that either your service hasn’t started handling traffic yet, or no monitored functions have been triggered.

Solution

  1. Ensure your application is actively running and receiving traffic (e.g., HTTP requests, queue jobs, scheduled tasks).
  2. Verify that your functions are being invoked and that they fall within files mapped by Hud.
  3. Useregister({ verbose: true }) to confirm that functions are registered and eligible for tracking.
  4. Double-check thatregister() was called early enough to capture your code correctly. See Option A – Preload for the preferred setup.


If you encounter any other issues or need further assistance, chat with our support team or email us at [email protected]. We're here to help!