Error Codes Reference

Error Message

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

Explanation

This error indicates that the SDK failed to initialize because the API key provided is either missing, malformed, or not recognized by the Hud backend.

Solution

To resolve this error:

1. Ensure your API key copied correctly exactly as seen in your Hud web application.
2. Check your secret management setup and verify that the API key is passed correctly to Hud.
3. Confirm key validity, login into the Hud web application and verify that the key is active and associated with your project.
4. Regenerate API key by contacting Hud support. Share the error code and message with [email protected] for further investigation and resolution.

Error Message

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

Explanation

This error occurs when the installed Node.js version is not supported by the SDK.

Solution

To resolve this error:

1. Check your Node.js version against the Support Matrix.
2. Update Node.js to a supported version.
3. Restart your service to apply the updated configuration.

Error Message

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

Explanation

This error is thrown when the SDK setup is called without a provided API key. Since the key is essential for authentication and initialization, the SDK cannot continue and shuts down gracefully.

Solution

To resolve this error:

1. Ensure the API key is set and provided to the initSession() function as the first parameter.
2. Check your secret management setup to verify the key is passed correctly to the SDK.
3. Contact Hud support, share the error code and message with [email protected] for further investigation and resolution.

Error Message

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

Explanation

This error occurs when the required serviceName parameter is missing during SDK setup. Hud uses this value to associate observability data with the correct service.

Solution

To resolve this error:

1. Ensure the service name is set and provided to the initSession() function as the second parameter.
2. Check for typos or undefined values in your setup logic.
3. Contact Hud support, share the error code and message with [email protected] for further investigation and resolution.

Error Message

Function initSession() was called before register(). Please make sure to call register() first.

Explanation

This error indicates an incorrect call order during initialization. The SDK requires register() to be called before initSession().

Solution

To resolve this error:

1. Callregister() before initSession() in your code.
2. Check your setup logic for execution order issues.

Error Message

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

Explanation

This error indicates that your application has exceeded the maximum number of instrumented functions allowed by the SDK. This helps prevent runtime performance issues.

Solution

To resolve this error:

1. Reduce the number of instrumented functions below the limit by removing modules from includeModules.
2. Contact [email protected] to request a higher limit.

Error Message

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

Explanation

The SDK checks memory availability to prevent runtime crashes. This error means the container or pod has less memory than the required minimum.

Solution

To resolve this error:

1. Increase pod/container memory limits to meet or exceed the minimum.
2. Review your infrastructure configuration (e.g., Kubernetes or Docker).
3. Contact your platform team if memory settings are managed centrally.

Error Message

Did not load as debugger is attached.

Explanation

This error indicates that the SDK detected an active debugger session during initialization. To avoid unintended behavior or security issues, the SDK does not load when a debugger is attached.

Solution

To resolve this error:

1. Detach the debugger before launching the application or initializing the SDK.
2. Ensure production environments are free of attached debugging tools.

Error Message

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

Explanation

This warning appears when the environment variable HUD_ENABLE is set to false. It is an intentional disablement and not an error.

Solution

• No action required unless this behavior is unintended.
• To enable the SDK, set HUD_ENABLE=true in your environment configuration or remove the environment variable.