Docs
Start typing to search…

Troubleshooting SDK Errors

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

Common Issues

I'm stuck on the first screen of integration

Look for console stdout prints of Hud, if there are none - Hud's SDK wasn't initialized properly. This usually happens due to:

  1. The SDK's init wasn't called, make sure to add --require with the entry point file at your console command, or import it in your code.

I see the service is recognized, but no code is mapped yet

This usually means that Hud's SDK did not map any of your code, and could happen due to several reasons:

  1. The call to register() was too early, refer to error E1026 for troubleshooting.
  2. The service ran for a short period - make sure to run the service for a period longer than 1 minute for everything to arrive.

I see code is mapped but no metrics arrive

This usually means that Hud's SDK did not collect any function invocations metrics, this could happen due to:

  1. No code was running, try invoking your code and watch the console stdout.
  2. The call to register() was too early, refer to error E1026 for troubleshooting.
  3. The service ran for a short period - make sure to run the service for a period longer than 1 minute for everything to arrive.

I don't see any endpoints

This usually means that Hud's SDK did not collect any data about your HTTP endpoints, this could happen due to:

  1. No endpoints we're invoked. Some frameworks require the endpoint to be invoked in order to be mapped. Invoked your endpoints and wait a 1-2 minutes for the data to arrive.
  2. Your HTTP framework is not supported. Check the Support Matrix for further details.
  3. The call to register() was too early, refer to error E1028 for troubleshooting.

E1011 - Provided key is invalid

Error Message

Hud: 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

Hud: 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

Hud: 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

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

Explanation
The required serviceName parameter was missing during SDK setup or it is invalid.

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: 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

Hud: 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, possibly remove modules added via includeModules.

E1023 - Pod memory limit too low

Error Message

Hud: 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

Hud: 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.

See Import Hud as early as possible to understand why early loading matters and how to do it 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.

See Import Hud as early as possible to understand why early loading matters and how to do it correctly.

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.

See Import Hud as early as possible to understand why early loading matters and how to do it correctly.

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. See Import Hud as early as possible to understand why early loading matters and how to do it correctly.

E1034 - Lambda support is in beta

Error Message

Hud: Can’t load Hud – Lambda support is currently in beta. Contact Hud to get early access.

Explanation

Hud’s support for AWS Lambda is currently in limited beta and requires specific setup via a Lambda Layer. If you’re seeing this message, your function is not instrumented correctly, or you don’t yet have access to the beta program.

Solution

  1. Request early access to Lambda support by contacting our team:

    Chat with our support team or email us at [email protected] to join the beta program and get setup instructions.

  2. Ensure your Lambda function is configured to use the Hud Layer as described in the beta documentation once access is granted.


E1035 - Bun not supported

Error Message

Hud: Hud does not support Bun yet. The SDK has initiated a graceful shutdown. Your application remains unaffected. See the compatibility matrix for details: https://docs.hud.io/docs/hud-sdk-compatibility-matrix-for-node

Explanation

Hud currently does not support the Bun runtime, and will not initialize in environments running on Bun. This is a graceful exit - your application will continue to run normally, but without any Hud data collection.

Solution

  1. Refer to the compatibility matrix to confirm supported runtimes.
  2. Switch to a supported runtime such as Node.js (LTS version) to enable Hud functionality.

E1036 - Windows not supported

Error Message

Hud: Hud does not support Windows yet. The SDK has initiated a graceful shutdown. Your application remains unaffected. See the compatibility matrix for details: https://docs.hud.io/docs/hud-sdk-compatibility-matrix-for-node

Explanation

Hud is currently not compatible with the Windows operating system. When running on Windows, the SDK shuts down gracefully to avoid interfering with your application. Your service continues to run normally, but no performance or tracing data will be collected by Hud.

Solution

  1. Refer to the compatibility matrix to confirm supported environments.
  2. Run your service in a supported OS like Linux, or deploy on a cloud-native runtime.

E1037 - Unsupported native platform

Error Message

Hud: Hud does not support this platform yet. The SDK has initiated a graceful shutdown. Your application remains unaffected. See the compatibility matrix for details: https://docs.hud.io/docs/hud-sdk-compatibility-matrix-for-node

Explanation

Hud relies on native bindings and system-level hooks that are only available on specific platforms. If your application is running in an environment that is not yet supported - such as an uncommon OS or custom runtime - Hud cannot initialize and will shut down safely to avoid disrupting your application.

Solution

  1. Check the compatibility matrix to verify supported platforms and runtimes.
  2. Run your application in a supported environment, such as Linux or macOS with a Node.js LTS version.

E1038 - ts-node used without transpileOnly

Error Message

Hud: Detected ts-node is used without the transpileOnly flag, which is not supported yet. SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation

Hud requires ts-node to run in transpileOnly mode in order to work correctly with minimal impact. Without this flag, ts-node performs full type checking and uses a different module loading pipeline, which might impact performance significantly.

Solution

Enable transpileOnly mode using one of the following methods:

  1. CLI Flag
    When running your app, pass the flag directly:

    ts-node --transpileOnly index.ts

  2. Environment Variable
    Set the environment variable TS_NODE_TRANSPILE_ONLY=true:

    export TS_NODE_TRANSPILE_ONLY=true

  3. Programmatic Configuration
    If you're initializing ts-node manually in your code, set the following option:

    require('ts-node').register({ transpileOnly: true });

  4. tsconfig.json (if usingts-node with config awareness)
    In some setups, you can set this via the tsconfig.json file:

    {
  "ts-node": {
    "transpileOnly": true
  }
}

E1039 - ts-node could not be resolved

Error Message

Hud: 'ts-node' was detected but could not be resolved by Hud. This may happen if 'ts-node' is installed globally. Try installing it locally in your project. The SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation

When using ts-node, Hud must be able to require the module during initialization. If ts-node is not available in your local node_modules, Hud cannot instrument your code and will shut down gracefully. This often occurs when:

  • ts-node is installed globally rather than locally
  • Your project’s dependency tree is misconfigured
  • A custom loader setup obscures Hud’s ability to detect ts-node

Solution

  1. Installts-node locally in your project:

    npm install ts-node
# or
yarn add ts-node

  2. Avoid using globally installedts-node. Run scripts using your local version:

    npx ts-node --transpileOnly index.ts
#or
node --require ts-node/register main.ts

  3. Ensure Hud runs in the same context as your local project and dependencies (e.g., avoid calling via detached scripts or mixed environments).


E9001 - SDK shut down during initialization

Error Message

Hud: SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation

This error means that the Hud SDK was unable to complete its startup sequence and shut down gracefully. This occurs when the SDK cannot fully initialize the background worker responsible for processing and transmitting Hud data.

This can happen in the following situations:

  1. Node Worker failed to start or communicate – the internal messaging layer did not initialize properly.
  2. Environment issues – including missing permissions, invalid configuration, or blocked file system access.

Solution

  1. Ensure the SDK is correctly installed and not modified – reinstall hud-sdk.
  2. Check for custom sandboxing or runtime limitations (e.g., serverless cold starts, restricted file I/O).
  3. Review container or OS-level constraints (e.g., memory, file permissions) that may prevent the worker from launching.
  4. Chat with our support team or email us at [email protected].

E9002 - SDK shut down due to a communication failure

Error Message

Hud: SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation

This error is triggered when the SDK fails to communicate with the Hud backend after several retry attempts. This occurs when the SDK's HTTP client exceeds the retry limit (default: 3) while attempting to reach a backend endpoint.

Common causes include:

  • Persistent network connectivity issues (disconnections, DNS failures, timeouts)
  • Custom or untrusted certificates in environments with custom CAs
  • Proxy, firewall, or outbound rules blocking the SDK
  • Temporary issues on the Hud backend

Solution

  1. Ensure your environment can reachhttps://api-prod.hud.io from the runtime host.
  2. If using a private CA or self-signed certificate, set the following: 
    export NODE_EXTRA_CA_CERTS=/path/to/your/ca.pem
    This lets Node.js trust your custom certificate chain.
  3. Verify proxy/firewall settings to ensure outbound requests are allowed.

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!

Updated about 1 month ago

What’s Next