The Hud Python SDK surfaces a numbered error code (for example E0003) with every user-facing log message. Find the code below to understand the cause and the fix.

Most errors are non-fatal: when Hud can't run, it shuts itself down gracefully and your application keeps running normally, just without Hud data.

Identity & configuration

E0001 - HUD_SERVICE not set

Error Message

Can't load Hud. Please set service name.

Explanation

Hud needs a service name to identify your code as a distinct service. It can be passed to init_session(), to the hud-run CLI via --service, or through the HUD_SERVICE environment variable. None was provided.

Solution

Set the service name using any of the following:

hud-run --key <hud_api_key> --service <your_service_name> python main.py

hud_sdk.init_session("<hud_api_key>", "<your_service_name>")

HUD_SERVICE=your-service-name

E0002 - HUD_SERVICE invalid

Error Message

Can't load Hud. Please set a valid service name.

Explanation

A service name was provided but is not a valid, non-empty string.

Solution

Ensure the service name is a non-empty string that serves as a meaningful, unique identifier for your service.

E0003 - HUD_KEY not set

Error Message

Can't load Hud. Please set API key.

Explanation

Hud needs your private API key to authenticate. It can be passed to init_session(), to the hud-run CLI via --key, or through the HUD_KEY environment variable. None was provided.

Solution

Set the API key using any of the following:

hud-run --key <hud_api_key> --service <your_service_name> python main.py

hud_sdk.init_session("<hud_api_key>", "<your_service_name>")

HUD_KEY=your-api-key

If you don't have an API key, contact [email protected] to obtain one.

E0004 - HUD_KEY invalid

Error Message

Can't load Hud. Please set a valid API key.

Explanation

An API key was provided but is not a valid, non-empty string. This refers to the structure of the value (missing or not a valid string), not its authentication validity.

Solution

Ensure the API key is a valid, non-empty string. If you don't have one, contact [email protected].

E0005 - HUD_TAGS invalid type

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

The optional HUD_TAGS value is not a dictionary of string key-value pairs. Hud ignores the tags and continues running without them.

Solution

Provide tags as a dictionary of strings:

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

E0006 - HUD_TAGS with dots

Error Message

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

Explanation

Tag keys can't contain dots (.). Hud automatically replaces them with underscores (_), but it's recommended to avoid dots to prevent inconsistencies.

Solution

Replace dots with underscores in your tag keys:

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

E0007 - HUD_TAGS invalid JSON

Error Message

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

Explanation

The HUD_TAGS value is not a valid JSON string. Hud defaults to empty tags.

Solution

Provide a valid JSON object of string key-value pairs:

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

E0012 - Python executable not found

Error Message

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

Explanation

Hud spawns a helper process using the Python interpreter, but couldn't locate the Python executable in your environment.

Solution

Set the HUD_PYTHON_BINARY_PATH environment variable to the absolute path of your Python executable:

HUD_PYTHON_BINARY_PATH=/usr/local/bin/python

If the issue persists, contact [email protected].

Register placement & data collection

These warnings mean Hud loaded but couldn't fully map your code — usually because register() (or the hud-run CLI) ran too late, after part of your code or a framework had already been imported. Your application keeps running normally, but with partial Hud data.

E0026 - register() not called before init_session()

Error Message

Please call 'register()' before 'init_session()'. Your application remains unaffected.

Explanation

init_session() was called without first calling register(). When you use the hud-run CLI this is handled for you; this error applies to manual, in-code initialization.

Solution

Call register() as early as possible, then init_session():

import hud_sdk

hud_sdk.register(hud_sdk.RegisterConfig())
hud_sdk.init_session("<hud_api_key>", "<your_service_name>")

For full coverage, prefer the hud-run CLI.

E0032 - Framework imported before register()

Error Message

The framework(s): ... was imported before register(). This means Hud might track partial framework invocations. Please move register() call to an earlier location.

Explanation

A supported framework (e.g. FastAPI, Flask, Django) was imported before Hud was registered, so Hud may only capture partial framework invocations.

Solution

Move register() (or the hud-run CLI) to the earliest possible point in your entry file, before any framework imports.

E0033 - Code files imported before register()

Error Message

N 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}).

Explanation

Some of your modules were imported before Hud registered, so those functions won't be instrumented.

Solution

Move register() earlier. To see exactly which files were loaded too early, enable verbose logging:

hud_sdk.register(hud_sdk.RegisterConfig(verbose=True))

E0034 / E0035 - Code mapped, but no activity tracked

Error Message

Code mapped successfully, but no function activity was tracked. Make sure your service is running and actively handling requests.

Explanation

Hud mapped your code but never observed any function executing. This usually means the service wasn't exercised (no requests/messages) during the run.

Solution

Make sure your service is running and actively handling traffic, then trigger the functions you want to measure.

E0036 - No code mapped

Error Message

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.

Explanation

Hud didn't map any code, almost always because register() ran after your code was already imported.

Solution

Move register() (or the hud-run CLI) to the very top of your entry file.

Environment not supported

E0022 - Insufficient memory

Error Message

Insufficient memory available. Minimum required: (<N>MB). SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation

The available memory is below the minimum Hud requires to run safely, so it shut down gracefully.

Solution

Increase the memory available to your pod/container. The minimum can be tuned via the min_pod_memory_mb field on RegisterConfig.

E0024 - GIL not enabled

Error Message

Hud is not supported without GIL. Please enable GIL. Your application remains unaffected.

Explanation

Hud does not support free-threaded (no-GIL) Python builds.

Solution

Run your service on a standard Python build with the GIL enabled.

E0025 - JIT enabled

Error Message

Hud is not supported with JIT. Please disable JIT. Your application remains unaffected.

Explanation

Hud does not support running with the experimental Python JIT enabled.

Solution

Disable the JIT for your service.

Limits reached

E0020 - File too large to monitor

Error Message

File is too large to be monitored, skipping. Path: <path>. File size: <N> bytes.

Explanation

A source file exceeded the maximum size Hud will parse, so it was skipped. Other files are unaffected.

Solution

No action is usually required. The limit can be tuned via the max_file_size_bytes field on RegisterConfig.

E0021 - Instrumented functions limit exceeded

Error Message

SDK limit of <N> instrumented functions exceeded. Hud will provide partial data. Your application remains unaffected.

Explanation

Your codebase has more functions than Hud's mapping limit, so only a subset is instrumented.

Solution

No action is usually required. The limit can be tuned via the max_mapped_functions field on RegisterConfig.

E0023 - Processes limit exceeded

Error Message

SDK limit of <N> processes exceeded. Hud will provide partial data. Your application remains unaffected.

Explanation

More processes than Hud's per-service limit tried to register, so some are not monitored.

Solution

No action is usually required. Contact [email protected] if you expect a higher process count.

Config file (hud_config.py)

These errors relate to the --config file passed to the hud-run CLI.

E0027 - Config file not found

Error Message

Config file not found: <path>, cwd: <cwd>.

Solution

Check that the path passed to --config exists relative to the working directory shown in the message.

E0028 - Config file is not a Python file

Error Message

Config file is not a Python file: <path>.

Solution

Point --config at a .py file (for example hud_config.py).

E0029 - Failed to load config file

Error Message

Failed to load config file: <path>, error: <error>.

Solution

The config file raised an error while importing. Fix the error shown in the message.

E0030 - Config file does not export config

Error Message

Config file does not export config variable.

Explanation

The config file must define a module-level variable named config.

Solution

# hud_config.py
import hud_sdk
config = hud_sdk.RegisterConfig()  # the variable name must be `config`

E0031 - config is not a RegisterConfig

Error Message

Config variable is not a RegisterConfig object.

Solution

Make sure the exported config variable is an instance of hud_sdk.RegisterConfig.

Context & manual flows

E0046 - Failed to set context

Error Message

Failed to set context.

Explanation

set_context() could not attach metadata to the current execution. See Setting Custom Context.

E0047 - Writeable directory not usable

Error Message

Failed to use the provided writeable directory: <dir>. Falling back to default locations. Please ensure the directory exists and is writeable.

Explanation

The directory provided via writeable_dir / HUD_WRITEABLE_DIR couldn't be used, so Hud fell back to its default locations.

Solution

Ensure the directory exists and is writeable by your service, or remove the override to use the defaults.

E0048 - Manual flow called before register()

Error Message

Manual flow API was called before register() and was skipped. Please call register() before using the manual flow API.

Solution

Ensure register() runs before any manual flow call. See Mark as Flow.

E0049 - Invalid flow name

Error Message

Manual flow API was called with an invalid flow name and was skipped. Flow names must be non-empty strings.

Solution

Pass a stable, non-empty string as the flow name. Put variable data in set_context instead.

E0051 - Nested manual flow

Error Message

Manual flow API was called inside an existing flow and was skipped. Nested flows are ignored and the parent flow is used.

Explanation

A flow was started inside an already-active flow (or inside an HTTP request). Manual flows can't be nested; the parent flow is used.

E0052 - end_flow() without start_flow()

Error Message

end_flow() was called without an active flow started by start_flow() and was skipped.

Solution

Pair every start_flow() with exactly one end_flow(), including on the error path.

E0053 - Queue args not supported on decorator

Error Message

enqueued_at and message_count are not supported when using a decorator and were ignored.

Explanation

enqueued_at and message_count apply per-invocation, so they can't be passed to the decorator form. Use the context manager or start_flow() for queue metadata.

E0054 - Custom flow ids limit exceeded

Error Message

SDK limit of <N> custom flow ids exceeded. The flow was skipped and Hud will provide partial data. Your application remains unaffected.

Explanation

Too many distinct custom flow names were created. Avoid high-cardinality flow names (e.g. embedding IDs or timestamps).

Solution

Use stable flow names and move variable data into set_context.

E0055 - enqueued_at is not timezone-aware

Error Message

enqueued_at must be a timezone-aware datetime and was ignored. Pass a datetime with tzinfo set.

Solution

Pass a timezone-aware datetime (with tzinfo set) for enqueued_at.

E0056 - Queue end-to-end duration dropped

Error Message

Manual queue flow end-to-end duration was out of range and was dropped. Ensure enqueued_at is correct and precedes processing by less than a year.

Solution

Ensure enqueued_at is correct and precedes processing by less than a year.

Graceful shutdowns (contact support)

E0008–E0011, E0013–E0017 - Internal graceful shutdown

Error Message

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

Explanation

Hud encountered an internal issue (for example, it couldn't start its helper process or communicate with its manager) and shut itself down. Your application is unaffected.

Solution

Share the exact error code and message with [email protected] for investigation.

E0018 - SDK imported but not initialized

Error Message

SDK imported but not initialized. Please ensure to call 'init_session()' to initialize the SDK.

Explanation

hud_sdk was imported, but init_session() was never called within the initialization timeout, so Hud never started collecting data.

Solution

Call hud_sdk.init_session(...) early in your service, or start it with the hud-run CLI. See the Python Installation Guide.

E0019 - General error

Error Message

Can't load Hud due to a general error, please contact support.

Explanation

Hud hit an unexpected error during initialization.

Solution

Contact [email protected] with the error message so we can investigate.