Troubleshooting SDK Errors

Error Message

Did not load as HUD_ENABLE is undefined. Please set HUD_ENABLE=true to run Hud.

Explanation
This error occurs because the HUD_ENABLE environment variable is not set in your service. The Python SDK requires this variable to be defined and set to true in order to initialize and run Hud.

When the SDK attempts to initialize the Hud service, it checks for the presence of this variable. If it is not defined, the initialization process halts to prevent improper behavior.

Solution
To resolve this error:

1. Add the HUD_ENABLE environment variable to your service configuration:
   1. Open your service's configuration file or environment setup.
   2. Add the following line to define the variable:

      HUD_ENABLE=true

2. Restart your service to apply the updated configuration
3. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

Did not load as HUD_ENABLE is set to a non-true value. Please set HUD_ENABLE=true to run Hud.

Explanation
This error occurs when the HUD_ENABLE environment variable is defined but is not set to a "true-y" value. The Python SDK interprets any value other than true (case-insensitive) as false, causing the Hud component to not be active during initialization.

Solution
To resolve this error:

1. Check the value of the HUD_ENABLE environment variable in your service configuration:
   1. Ensure that it is explicitly set to true (case-insensitive).
2. Update the environment variable:
   1. Change the value of HUD_ENABLE to:

      HUD_ENABLE=true

3. Restart your service to apply the updated configuration
4. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

Can't load Hud, HUD_SERVICE was not set. Please set service name using the env var HUD_SERVICE.

Explanation
This error occurs because the HUD_SERVICE environment variable is not set in your service configuration. The Python SDK requires this variable to identify your code as a distinct service. Without a valid HUD_SERVICE value, the Hud component cannot initialize.

The HUD_SERVICE variable must be:

• A non-empty string.
• A unique identifier for the service.

Solution
To resolve this error:

1. Add the HUD_SERVICE environment variable to your service configuration:
   1. Open your service's configuration file or environment setup.
   2. Add the following line, replacing your-service-name with the desired service name:

      HUD_SERVICE=your-service-name

2. Restart your service to apply the updated configuration
3. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

Can't load Hud, HUD_SERVICE value has invalid service name. Please set service name using the env var HUD_SERVICE.

Explanation
This error occurs when the HUD_SERVICE environment variable is defined but contains an invalid value.

The HUD_SERVICE variable must be:

• A non-empty string.
• A unique identifier for the service.

Solution
To resolve this error:

1. Validate the HUD_SERVICE environment variable: Ensure that the value of HUD_SERVICE is a non-empty string that serves as a meaningful and unique identifier for your service.
2. Update the environment variable:
   Modify the service configuration or environment setup to include a valid service name:

   HUD_SERVICE=your-valid-service-name

3. Restart your service to apply the updated configuration
4. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

Can't load Hud, HUD_KEY was not set. Please set API key using the env var HUD_KEY.

Explanation
This error occurs because the HUD_KEY environment variable is not set in your service configuration. The Python SDK requires this private API key to authenticate and enable the Hud service. Without a valid HUD_KEY, the initialization process will fail.

Solution
To resolve this error:

1. Add the HUD_KEY environment variable to your service configuration:
   1. Open your service's configuration file or environment setup.
   2. Add the following line, replacing your-api-key with your private API key:

      HUD_KEY=your-api-key

2. If you do not have a private API key: Contact [email protected] to obtain one.
3. Restart your service to apply the updated configuration.
4. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

Can't load Hud, HUD_KEY value has invalid API key. Please set a valid key in env var HUD_KEY.

Explanation
This error occurs when the HUD_KEY environment variable is defined but contains an invalid value. The Python SDK expects the HUD_KEY to be a non-empty string. This error specifically refers to issues with the structure of the input (e.g., the key is missing or not a valid string) rather than its authentication validity.

Solution
To resolve this error:

1. Validate the HUD_KEY environment variable: Ensure that the value of HUD_KEY is a valid, non-empty string.
2. Update the environment variable:
   Modify the service configuration or environment setup to include a properly formatted API key:

   HUD_KEY=your-api-key

3. If you do not have a private API key: Contact [email protected] to obtain one.
4. Restart your service to apply the updated configuration.
5. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

HUD_TAGS should be of type Dict[str, str], Hud will run without tags. Please set valid tags in env var HUD_TAGS.

Explanation
This error occurs when the optional HUD_TAGS environment variable is provided but is not formatted as a dictionary of string key-value pairs (Dict[str, str]). Tags are used to provide additional metadata about the service, but if the format is invalid, Hud will ignore the tags and continue running without them.

The expected format is a dictionary where both the keys and values are strings, for example:

{"key1": "value1", "key2": "value2"}

Solution
To resolve this error:

1. Validate the format of HUD_TAGS: Ensure the HUD_TAGS environment variable is a properly formatted dictionary of strings.
2. Set the environment variable with valid tags:

   HUD_TAGS={"key1": "value1", "key2": "value2"}

3. Restart your service to apply the updated configuration.
4. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

HUD_TAGS keys can't contain dots, they have been replaced with underscores.

Explanation
This error occurs when the optional HUD_TAGS environment variable is provided and contains keys with dots (.). The Python SDK does not support dots in tag keys, and they are automatically replaced with underscores (_) to ensure compatibility.

While the SDK can handle this substitution, it is recommended to avoid using dots in tag keys to prevent unexpected behavior or inconsistencies.

Solution
To resolve this error:

1. Update the format of HUD_TAGS:
   1. Ensure that the keys in the HUD_TAGS dictionary do not contain dots.
   2. Replace any dots with underscores manually before setting the environment variable.

      HUD_TAGS={"key_one": "value1", "key_two": "value2"}

2. Set the updated environment variable: Modify your service configuration or environment setup to include the corrected tags.
3. Restart your service to apply the updated configuration.
4. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

HUD_TAGS is not a valid JSON, defaulting to empty tags. Please set valid textual tags in env var HUD_TAGS.

Explanation
This error occurs when the optional HUD_TAGS environment variable is provided but is not a valid JSON string. The Python SDK requires HUD_TAGS to be a JSON-formatted string representing a dictionary of key-value pairs (e.g., Dict[str, str]). If the format is invalid, the SDK will default to using empty tags, and no metadata will be applied.

Solution
To resolve this error:

1. Validate the JSON structure of HUD_TAGS:
   1. Ensure the HUD_TAGS environment variable contains a valid JSON string. The string should represent a dictionary where both the keys and values are strings.
   2. Example of a valid format:

      HUD_TAGS={"key_one": "value1", "key_two": "value2"}

2. Correct the environment variable: Update your service configuration or environment setup with a properly formatted JSON string.
3. Restart your service to apply the updated configuration.
4. Verify the installation: Follow the full installation guide to ensure all prerequisites are met and the SDK is set up correctly: Hud Python Installation Guide

Error Message

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

Explanation
This error indicates that the SDK has encountered an internal issue and has performed a graceful shutdown to ensure your application remains unaffected.

Contact Hud Support: Share the error code and message with [email protected] for further investigation and resolution. Hud support will provide detailed guidance to resolve this issue promptly.

Error Message

Can't load Hud, Python executable was not found. Please set HUD_PYTHON_BINARY_PATH with the python executable path.

Explanation
This error indicates that the SDK has encountered an internal issue and has performed a graceful shutdown to ensure your application remains unaffected. While the exact cause of this issue is not disclosed, it is recommended to address this situation to ensure the SDK operates as expected.

Solution
To resolve this error:

1. Contact Hud Support: Share the error code and message with [email protected] for further investigation and resolution.
2. Verify the configuration: Ensure that all environment variables and setup prerequisites are correctly configured as per the: Hud Python Installation Guide
   Hud support will provide detailed guidance to resolve this issue promptly.

Error Message

Initialization aborted due to rate limit reached for concurrent services. Data for this run will not be sampled.

Explanation
This error occurs when the SDK attempts to initialize but cannot proceed due to reaching the rate limit for concurrent services. As a result, Hud will not sample data for this run, and the associated data will be lost.

Solution
To resolve this error:

1. Contact Hud Support: Reach out to [email protected] for assistance with resolving rate limitation issues.
   Hud support will provide detailed guidance to resolve this issue promptly.