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
- 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
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
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
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
- 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_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
- 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
- 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
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.
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.
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.
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.
Updated 5 days ago