The Hud Java agent prints user-facing lines as Hud: {message}. A numbered code (for example E1002) is included when the line comes from the error catalog. Find the code below.

Most of these are non-fatal. When Hud cannot run, it shuts itself down and your application keeps running, without Hud data. A shutdown line is followed by Hud: Detaching HUD.

---

Common issues

Nothing from Hud in the logs

The agent never started. Attach it on the JVM command with -javaagent:./hud-sdk.jar, and set HUD_KEY and HUD_SERVICE. See Java Installation.

The service is recognized, but no code is mapped

io.hud.includeDomains did not match any of your classes. See E1007 and E1014.

Code is mapped, but no metrics arrive

The process has not recorded a function invocation yet. Invoke the code you care about and wait a minute or two. See E3007. A process that exits in a few seconds can exit before the first export.

No endpoints

The framework is outside the compatibility matrix, or a request has not been served yet. Spring MVC, the Servlet API, Jersey on a servlet, and http4k HTTP routes are automatic. See E1017, E1020, and E1029.

---

Identity and startup

E1001 - HUD_ENABLE is false

Error Message

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

Explanation

HUD_ENABLE=false is the switch that keeps the agent from running.

Solution

Unset HUD_ENABLE, or set it to a value other than false, and restart the process.

---

E1002 - HUD_KEY not set

Error Message

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

Explanation

HUD_SERVICE is set and HUD_KEY is missing or empty.

Solution

Set HUD_KEY to the API key for this environment from the API keys page, then restart.

---

E1003 - HUD_SERVICE not set

Error Message

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

Explanation

HUD_KEY is set and HUD_SERVICE is missing or empty.

Solution

Set HUD_SERVICE to the name Hud should show for this process, then restart.

---

E1004 - HUD_KEY and HUD_SERVICE not set

Error Message

Can't load Hud, HUD_KEY and HUD_SERVICE were not set.

Explanation

Both environment variables are missing or empty.

Solution

Set HUD_KEY and HUD_SERVICE, then restart.

---

E1007 - Include domains not set

Error Message

Include domains are not set. Please set them with the system property io.hud.includeDomains. SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation

The agent only instruments classes under the packages you name. None were set.

Solution

Pass a semicolon-separated list of package prefixes on the JVM command:

-Dio.hud.includeDomains=com.acme;com.example

---

E1012 - Failed to instrument the application

Error Message

Failed to instrument application. SDK has initiated a graceful shutdown. Your application remains unaffected.

Explanation

The agent attached, then failed while installing instrumentation. The application is left running without Hud.

Solution

Restart once. If it happens again, send the full Hud: lines to [email protected].

---

E1018 - Failed to initialize configuration

Error Message

Failed to initialize configuration

Explanation

Agent configuration could not be built. Hud detaches.

Solution

Send the full Hud: lines to [email protected].

---

E1019 - Failed to initialize instrumentation storage

Error Message

Failed to initialize instrumentation storage

Explanation

The agent could not allocate its instrumentation state. Hud detaches.

Solution

Send the full Hud: lines to [email protected].

---

Runtime guardrails

These checks run before instrumentation. On failure the agent disables itself and the application starts without Hud.

E1008 - Unsupported Java version

Error Message

Unsupported Java version {version} detected. Supported versions: {list}.

Explanation

The JVM major is not in the supported list. The default list is 8, 11, 17, 21, and 25.

Solution

Run on a major from the compatibility matrix.

---

E1009 - Java version could not be read

Error Message

Unable to determine Java version {java.version}.

Explanation

java.version was not a version the agent could parse.

Solution

Send the value of java.version to [email protected].

---

E1010 - Unsupported operating system

Error Message

Unsupported OS '{os.name}' detected.

Explanation

The JVM's os.name is on the unsupported list. Windows is rejected by default.

Solution

Run the JVM on Linux or macOS. A Linux container on a Windows host is fine: the JVM's operating system is what is checked.

---

E1011 - Not enough memory

Error Message

Insufficient memory available. Minimum required: {MB}MB.

Explanation

The JVM's maximum heap is below the minimum. The default minimum is 250 MB.

Solution

Raise -Xmx so the maximum heap is at least the number in the message.

---

E1022 - SecurityManager is active

Error Message

Active Java SecurityManager detected.

Explanation

A security manager is installed. The agent disables itself rather than run under it.

Solution

Start the JVM without a security manager.

---

E1023 - Unsupported JVM

Error Message

Unsupported JVM implementation '{vm.name}' detected.

Explanation

java.vm.name matched io.hud.guardrails.unsupportedJvmNames. That property is empty by default, so this line only appears when it has been set.

Solution

Remove the JVM name from io.hud.guardrails.unsupportedJvmNames, or run a JVM that is not on that list.

---

Session startup

E2001 - Invalid API key

Error Message

The provided key is invalid. Verify HUD_KEY.

Explanation

The Hud backend rejected HUD_KEY (HTTP 401 or 403).

Solution

Copy the key again from the API keys page for the environment this service should report to. Restart after changing it.

---

E2002 - Network error during initialization

Error Message

Network error during SDK initialization. Check internet connection, firewall settings, and DNS. The backend may be temporarily unavailable.

Explanation

The session request failed: a timeout, a DNS or connection error, or an HTTP 5xx from the backend.

Solution

Confirm the process can reach Hud on the network, then restart. If it keeps failing, contact [email protected].

---

E2005 - TLS certificate check failed

Error Message

SSL certificate verification failed during SDK initialization. Set io.hud.customCaCert if using a self-signed certificate.

Explanation

The JVM did not trust the certificate on the connection to Hud. This is the usual result of a TLS-inspecting proxy or a private CA.

Solution

Point io.hud.customCaCert at the PEM file for that CA:

-Dio.hud.customCaCert=/path/to/ca.pem

---

E2008 - Session throttled

Error Message

Session throttled by backend.

Explanation

Hud accepted the connection and declined this session. The application keeps running without Hud data.

Solution

Contact [email protected].

---

After startup

E1013 - Instrumented function limit

Error Message

SDK limit of {max} instrumented functions exceeded.

Explanation

More methods matched io.hud.includeDomains than the agent will instrument. Hud detaches so the process is not left partially instrumented.

Solution

Narrow io.hud.includeDomains to the packages you want measured, then restart.

---

E1014 - No classes matched include domains

Error Message

No classes matched the configured include domains. Verify io.hud.includeDomains.

Explanation

The agent is running and has instrumented nothing. The package prefixes do not match the classes that loaded.

Solution

Set io.hud.includeDomains to a prefix of your packages, such as com.acme. A prefix that matches nothing, or only dependencies, produces this warning. Hud keeps running.

---

E1015 - Invalid configuration value

Error Message

Invalid value '{value}' for {property}, using default {default}.

Explanation

A system property the agent reads was not a valid value. Hud keeps the default named in the message.

Solution

Set that property to a valid value, or remove it to keep the default.

---

E1016 - Custom CA file not found

Error Message

Custom CA cert file not found: {path}. Continuing with the default trust store.

Explanation

io.hud.customCaCert is set and that path is not a file. Hud uses the JVM trust store.

Solution

Fix the path, or unset io.hud.customCaCert if you do not need a private CA.

---

E3001 - Heap stayed high

Error Message

Heap memory utilization remains consistently high.

Explanation

Heap usage stayed above the agent's threshold. Hud detaches so it does not add pressure.

Solution

Give the process more heap, or reduce what else it retains. Restart to load the agent again.

---

E3007 - No function activity yet

Error Message

Code instrumented successfully, but no function activity has been tracked yet. Make sure your service is handling requests.

Explanation

Methods were instrumented and none of them have run.

Solution

Invoke the service. A process that sits idle, or exits before a request, produces this warning and no metrics.

---

Frameworks

E1017 - Spring produced no endpoints

Error Message

Spring was detected but no HTTP endpoints were mapped. HTTP instrumentation may be partial or unavailable for this Spring version.

Explanation

Spring is on the classpath and no Spring HTTP endpoint was declared. spring-boot-starter-webflux is not instrumented. A Boot application that only hosts another framework still declares Boot's /error route and does not log this.

Solution

Use spring-boot-starter-web on a version from the compatibility matrix. For WebFlux, record the route with Mark as Flow (Flow.startHttp).

---

E1020 - http4k produced no routes

Error Message

http4k was detected but no HTTP routes were recorded. HTTP instrumentation may be partial or unavailable for this http4k version or server backend.

Explanation

http4k handled traffic and no HTTP route was recorded. SSE and WebSocket routers are not measured.

Solution

Use http4k 6.x and an HTTP router. Versions below 6.0.0.0 log E1028 instead.

---

E1028 - Library below its supported floor

Error Message

{framework} instrumentation is unavailable: the detected version is below the supported floor. Upgrade to {version} or later.

Explanation

The named library loaded and is older than the version in the message. Current floors are http4k 6.0.0.0, Jersey 2.8, and Kotlin coroutines 1.8.0. Hud keeps running; that library is not instrumented.

Solution

Upgrade the named library to at least the version in the message.

---

E1029 - JAX-RS produced no endpoints

Error Message

JAX-RS was detected but no HTTP endpoints were recorded. HTTP instrumentation may be partial or unavailable for this JAX-RS implementation or servlet container.

Explanation

A request reached Jersey's servlet boundary and no JAX-RS endpoint was recorded. Only servlet-hosted Jersey is measured.

Solution

Host Jersey as a servlet (org.glassfish.jersey.servlet.ServletContainer) on Jersey 2.8 or newer. Another JAX-RS stack, or Jersey on Grizzly, the JDK HTTP server, Netty, or Helidon, needs Mark as Flow.

---

Session tags

Tags are io.hud.tags.{name}={value} system properties. A bad tag is dropped or renamed. Hud keeps running.

E1024 - Tag name contained a dot

Error Message

io.hud.tags.* properties can't contain dots; they have been replaced with underscores.

Explanation

A tag name contained .. Hud stored it with _ in place of each dot.

Solution

Name the property without dots: -Dio.hud.tags.region=us-east-1.

---

E1025 - Tag name or value was empty

Error Message

io.hud.tags.* properties must contain non-empty keys and values; tags with empty keys or values have been ignored.

Explanation

A tag property had an empty name or an empty value. That tag was not sent.

Solution

Set both sides: -Dio.hud.tags.team=payments.

---

E1026 - Tag names collided

Error Message

io.hud.tags.* properties collided after dot normalization; duplicate keys were resolved by keeping the lexicographically first property.

Explanation

Two tag properties became the same name after dots were turned into underscores. Hud kept one of them.

Solution

Use one property per tag name.

---

Warnings without a code

These lines have no [E…] code. Each is logged once.