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:
- 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:
- The call to
register()
was too early, refer to error E1026 for troubleshooting. - 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:
- No code was running, try invoking your code and watch the console stdout.
- The call to
register()
was too early, refer to error E1026 for troubleshooting. - 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:
- 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.
- Your HTTP framework is not supported. Check the Support Matrix for further details.
- 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
- Ensure your API key is copied exactly from your Hud dashboard.
- Verify your secret management is correctly passing the key to your runtime.
- 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
- Check your Node.js version against the Support Matrix.
- Upgrade to a supported version if necessary.
- 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
- Pass the API key as the first argument to
initSession()
. - 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
- Provide a
serviceName
as the second argument toinitSession()
. - Check for typos or undefined values in your initialization code.
E1021 - HUD_ENABLE
is false
HUD_ENABLE
is falseError 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
- 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
- Increase memory limits in your container/pod spec (e.g., Kubernetes, Docker).
- Contact your platform team if limits are managed centrally.
- 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
- Detach the debugger before launching your application.
- Avoid using debuggers in production environments.
E1025 - register() not called before initSession()
Error Message
Hud:
register()
was not called, or called afterinitSession()
- please callregister()
beforeinitSession()
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
- Call
register()
beforeinitSession()
– ideally at the very start of your main file. - Ensure
register()
is not conditionally skipped. - 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
- Call
register()
at the very top of your main entry file, before importing or executing any other code. - Alternatively, use Option A – Preferred: Preload with
--require
from the integration guide to ensure Hud is loaded before your application. - Avoid placing
register()
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 moveregister()
call to an earlier location. To view the list of files useregister(\{‘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
- Move the
register()
call to the very top of your application’s entry point, before importing any other modules. - Use
register({ verbose: true })
to log which files were loaded too early and adjust your import order accordingly. - Prefer Option A – Preload with
--require
from the installation guide to guarantee proper loading. - Avoid placing
register()
inside conditionals or deferred execution paths.
E1028 - Framework loaded before register()
Error Message
Hud: Warning - The framework(s):
<framework_name>
was imported beforeregister()
. This means Hud won’t track your framework invocations. Please moveregister()
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
- Move the
register()
call to the very top of your entry file, before importing any framework like Express or Koa. - Ensure
register()
runs before any server setup logic. - 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
- Check your framework version (e.g., Express, NestJS).
- Refer to the compatibility matrix to verify support.
- If possible, upgrade or downgrade to a compatible version to restore full functionality.
-
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
- Refer to the compatibility matrix to check supported frameworks.
- Consider switching to a supported framework if full HTTP visibility is important for your use case.
-
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
- Move the
register()
call to the top of your main entry file, before importing any queue framework. - Ensure
register()
is not conditionally delayed or wrapped in async logic. - 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
- Ensure your application is actively running and receiving traffic (e.g., HTTP requests, queue jobs, scheduled tasks).
- Verify that your functions are being invoked and that they fall within files mapped by Hud.
- Use
register({ verbose: true })
to confirm that functions are registered and eligible for tracking. - Double-check that
register()
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
-
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. -
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
- Refer to the compatibility matrix to confirm supported runtimes.
- 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
- Refer to the compatibility matrix to confirm supported environments.
- 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
- Check the compatibility matrix to verify supported platforms and runtimes.
- Run your application in a supported environment, such as Linux or macOS with a Node.js LTS version.
E1038 - ts-node used without transpileOnly
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:
-
CLI Flag
When running your app, pass the flag directly:ts-node --transpileOnly index.ts
-
Environment Variable
Set the environment variableTS_NODE_TRANSPILE_ONLY=true
:export TS_NODE_TRANSPILE_ONLY=true
-
Programmatic Configuration
If you're initializingts-node
manually in your code, set the following option:require('ts-node').register({ transpileOnly: true });
-
tsconfig.json (if using
ts-node
with config awareness)
In some setups, you can set this via thetsconfig.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
-
Install
ts-node
locally in your project:npm install ts-node # or yarn add ts-node
-
Avoid using globally installed
ts-node
. Run scripts using your local version:npx ts-node --transpileOnly index.ts #or node --require ts-node/register main.ts
-
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:
- Node Worker failed to start or communicate – the internal messaging layer did not initialize properly.
- Environment issues – including missing permissions, invalid configuration, or blocked file system access.
Solution
- Ensure the SDK is correctly installed and not modified – reinstall
hud-sdk
. - Check for custom sandboxing or runtime limitations (e.g., serverless cold starts, restricted file I/O).
- Review container or OS-level constraints (e.g., memory, file permissions) that may prevent the worker from launching.
-
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
- Ensure your environment can reach
https://api-prod.hud.io
from the runtime host. - If using a private CA or self-signed certificate, set the following:
This lets Node.js trust your custom certificate chain.
export NODE_EXTRA_CA_CERTS=/path/to/your/ca.pem
- Verify proxy/firewall settings to ensure outbound requests are allowed.
Updated 29 days ago