Troubleshooting Glossary & FAQ

​

🛠️ Step-by-Step Error Resolutions

​

1. Agent Fails to Start: Missing commitSha

[HyperProbe] CRITICAL: Failed to start agent. A valid "commitSha" is required via options or the GIT_COMMIT environment variable...

• Cause: HyperProbe.start() was called without a commitSha option, and the GIT_COMMIT environment variable is either empty or set to "unknown". The agent refuses to run because it cannot map source code coordinates safely without a specific git reference.
• Solution: Provide the active commit SHA during build-time or runtime:
  # Recommended: Set it in your startup script
  GIT_COMMIT=$(git rev-parse HEAD) node dist/index.js
  

​

2. Probe Gutter Icon Shows Hollow Orange Dot (Agent Not Going Live)

• What you see: A probe is successfully inserted inside VS Code, but the gutter indicator stays orange.
• Cause: The VS Code extension has registered the probe on the server, but the SDK agent is either offline, unreachable, or configured with mismatched service coordinates.
• Solution:
  1

  Verify Service ID Alignment

  Open your local project’s .hprc file and compare its serviceId exactly (case-sensitive) with the serviceId passed to HyperProbe.start() in your server code:

  .hprc

  { "serviceId": "billing-api" }
  

  src/app.ts

  HyperProbe.start({ serviceId: 'billing-api' }); // Must match .hprc!
  

  2

  Check the Broker URL Connection

  Ensure your container can resolve and access the Broker server. Try curling the health endpoint directly from inside the application’s hosting shell:

  curl https://logger.app.hyperprobe.co/health
  

  3

  Match Environments

  Verify that the environment dropdown selected inside your VS Code extension panel (e.g., production) matches the environment parameter in your SDK initialization.

​

3. Gutter Gutter Icon Shows Error Status (Solid Red Dot)

• What you see: A probe’s status instantly transitions to ERROR.
• Cause: The agent received the instruction but could not parse the line coordinates or compile the breakpoint hook.
• Solution:
  • Non-Executable Line: Check if you placed the probe on a line containing comments, blank spaces, imports, type annotations (interface, type), or curly braces. Move the probe to an executable line containing a statement.
  • Missing Source Maps: For TypeScript or compiled projects, ensure "sourceMap": true is enabled in your compiler config, and that sourceMapDir and distLocation point to your built outputs so the agent can match coordinates.

​

4. Local Docker Connection Fails (http://localhost:3001)

• What you see: When running the SDK agent inside Docker but hosting the HyperProbe broker locally, the agent fails to connect.
• Cause: Inside a Docker container, localhost resolves to the container’s own loopback interface, not your machine’s host ports.
• Solution: Update your containerized agent’s brokerUrl config to use the host loopback alias:
  HyperProbe.start({
    // ...
    brokerUrl: 'http://host.docker.internal:3001' // Routes to your machine's host localhost!
  });
  

​

❓ Frequently Asked Questions

# Show everything
DEBUG=hyperprobe:* node dist/index.js

# Isolate specific layers
DEBUG=hyperprobe:agent      # General lifecycle and probe compilation
DEBUG=hyperprobe:broker     # Outbound sync and gRPC communication
DEBUG=hyperprobe:safety     # Event loop lag tracking and memory stats