HyperProbe Common Error Messages and How to Fix Them

Step-by-step fixes for the most frequent errors and unexpected behaviors you may encounter when setting up or running HyperProbe in your application.

This page covers specific error messages and failure modes you may encounter with the Node.js SDK, the VS Code extension, or your probe configuration. For general setup questions, see the FAQ.

---

Agent fails to start: missing commitSha

Error message:

[HyperProbe] CRITICAL: Failed to start agent. A valid "commitSha" is required via options
or the GIT_COMMIT environment variable to ensure accurate source map resolution and prevent
cross-deployment collisions.

Cause: HyperProbe.start() was called without a commitSha option, and the GIT_COMMIT environment variable is either unset or set to the string "unknown". The agent refuses to start in this state because without a commit SHA it cannot resolve source maps or guarantee that probes match the version of code running in production.

Solution: Supply the commit SHA via one of two methods:

Environment variable (recommended)

# Inject GIT_COMMIT at deploy time or in your process manager
GIT_COMMIT=$(git rev-parse HEAD) node dist/index.js

Most CI/CD platforms (GitHub Actions, GitLab CI, CircleCI) expose the commit SHA as a built-in environment variable. Map it to GIT_COMMIT in your deployment configuration so your application code stays clean.

---

Probe shows an orange dot — agent not going live

What you see: A probe is visible in the extension with an orange indicator next to it. The probe status shows as registered but no agent has been seen.

Cause: The agent started successfully but cannot reach the broker, or the serviceId or environment values do not match what the extension is looking for.

Solution:

1. Check the broker URL

   Verify that brokerUrl in your HyperProbe.start() call is correct and reachable from the machine running your application. Test connectivity directly:

   curl http://your-broker-host:50051
   # or for gRPC, check with grpcurl or your team's health check endpoint
   

   Enable broker logs to see exactly what’s happening:

   DEBUG=hyperprobe:broker node dist/index.js
   
2. Verify serviceId matches your .hprc file

   The serviceId passed to HyperProbe.start() must exactly match the serviceId field in your .hprc file. Open both and confirm they are identical — the comparison is case-sensitive.

   .hprc

   { "serviceId": "payment-service" }
   

   index.ts

   HyperProbe.start({
     serviceId: 'payment-service', // must match .hprc exactly
     ...
   });
   
3. Check the environment value

   The environment field passed to HyperProbe.start() must match the environment selected in the extension’s source selector. If your SDK is configured with environment: 'production' but the extension is scoped to staging, the agent and the extension will not find each other.

---

Probe stays ACTIVE but never captures data

What you see: A probe shows as ACTIVE (green indicator) but no snapshots appear even after the relevant code runs.

Possible causes and solutions:

The code path is never triggered

The instrumented line may be in a code path that isn’t being executed — such as an error handler, a rarely called branch, or an endpoint receiving no traffic. Trigger the path explicitly:

• Call the relevant endpoint or function manually.
• Use a load generator or test script to exercise the path.
• Check application logs to confirm the code block is being entered.

A probe condition is filtering out all executions

If you set a condition expression on the probe, HyperProbe only captures when the condition evaluates to true. If the condition is incorrect or always evaluates to false, you will never see a capture.

Remove the condition temporarily to verify the line is being hit at all. Once you confirm captures are working, re-add and refine the condition.

Source map mismatch — probe resolved to the wrong line

For TypeScript or bundled projects, a missing or stale source map can cause the probe to instrument a different line in the compiled output than the one you selected in your source file. Symptoms include the probe being ACTIVE with no captures, or captures appearing with unexpected variable names.

Check your source map configuration:

• Confirm sourceMapDir points to the directory containing your .js.map files.
• Ensure source maps were generated for the exact build currently running in production.
• If you recently redeployed, make sure GIT_COMMIT reflects the new commit so fresh source maps are uploaded.

---

Probe shows ERROR status

What you see: A probe’s status is ERROR in the extension.

Cause: The agent received the probe configuration but could not instrument the specified code location. This is typically a file path, line number, or instrumentation target problem.

Solution:

1. Verify the file path and line number

   Confirm that the file path is correct relative to your project root, and that the line number points to an executable statement — not a comment, blank line, import declaration, or type annotation.

   HyperProbe cannot instrument lines that contain no executable code. Move the probe to the nearest line with an actual statement.

2. Check source map configuration for TypeScript projects

   For TypeScript projects, ensure:

   • Source maps are enabled in your tsconfig.json ("sourceMap": true).
   • The compiled output and source maps were generated from the same build as the running process.
   • sourceMapDir in your SDK configuration points to the output directory.
3. Enable agent debug logs

   Run with DEBUG=hyperprobe:agent to see detailed logs about which probes the agent attempted to apply and which ones failed:

   DEBUG=hyperprobe:agent node dist/index.js
   

   Look for log lines referencing the probe ID shown in the extension.

---

Extension cannot find a .hprc file

What you see: The extension shows no services in the source selector, or shows a warning that no .hprc file was found in the workspace.

Cause: The .hprc file is missing from the workspace, is located in a subdirectory the extension doesn’t scan, or contains invalid JSON.

Solution: Create a .hprc file in the root of your project with valid JSON and a serviceId field:

.hprc

{
  "serviceId": "my-service"
}

The serviceId value must be a non-empty string and must match the serviceId passed to HyperProbe.start() in your application.

The extension automatically detects .hprc files anywhere in the open workspace using a recursive file watcher. If you add or update the file while VS Code is open, the extension picks it up within a few seconds without a reload.

If the file contains invalid JSON — such as trailing commas, unquoted keys, or JavaScript-style comments — the extension silently skips it. Validate your .hprc with a JSON linter if the file exists but the service still doesn’t appear.

---

Large objects are truncated in snapshots

What you see: Captured snapshots show objects with [truncated] markers or fewer properties than expected.

Cause: The agent applies data limits to prevent large captures from impacting production performance. The default limits are:

Setting	Default	Description
maxObjectDepth	3	Maximum levels of nested object traversal
maxObjectProperties	50	Maximum properties captured per object
maxArrayLength	3	Maximum array elements captured
maxStringLength	1024	Maximum characters captured per string

The architecture also enforces an absolute maximum snapshot size of 2 MB.

Solution: Increase the relevant limits in your SDK configuration:

HyperProbe.start({
  // ...required options
  maxObjectDepth: 5,
  maxObjectProperties: 100,
  maxArrayLength: 10,
  maxStringLength: 4096,
});

Alternatively, use Watch Expressions to capture a specific sub-property by path instead of the full root object. This is more precise and avoids increasing global limits.

Prefer narrow Watch Expressions over raising global depth limits in high-traffic services. Capturing user.address.city is far cheaper than traversing the entire user object to depth 5.

---

Safety guardrail triggered — instrumentation suspended (RED status)

What you see: The DEBUG=hyperprobe:safety logs show a RED status event, and probe captures stop for a period of time.

What happens: The safety monitor detected that instrumentation overhead exceeded a configured threshold — either the event loop lag exceeded maxLagMs or the pause budget (pauseBudgetMs) was consumed within a measurement window. The agent suspends all instrumentation and automatically resumes after the cooldownSec period (default: 10 seconds).

This is intentional behavior designed to protect your application. No manual intervention is required for a single occurrence.

If RED status occurs frequently:

1. Wait for automatic recovery first

   The agent resumes instrumentation automatically after the cooldown period. Check whether captures resume on their own before making configuration changes.

2. Reduce probe hit frequency

   Lower hitsPerSec to reduce how often the agent captures data per second:

   HyperProbe.start({
     // ...
     hitsPerSec: 5, // default is 10
   });
   
3. Relax the lag and budget thresholds

   If your application has naturally higher event loop variance, increase the thresholds to avoid false positives:

   HyperProbe.start({
     // ...
     maxLagMs: 100,      // default is 50 ms
     pauseBudgetMs: 40,  // default is 20 ms
     cooldownSec: 5,     // default is 10 seconds
   });
   
4. Check for a hot probe

   A single probe on a very hot code path (executed thousands of times per second) can trigger the safety guardrail repeatedly. Identify which probe is firing frequently using DEBUG=hyperprobe:stats logs and consider reducing its hit limit or removing it.

   DEBUG=hyperprobe:stats node dist/index.js