> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprobe.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Glossary & FAQ

> Step-by-step solutions to common errors, connectivity issues, and frequently asked questions.

Find instant solutions to setup errors, network connection blocks, and common usage questions.

***

## 🛠️ Step-by-Step Error Resolutions

### 1. Agent Fails to Start: Missing `commitSha`

**Error Message:**

```text theme={null}
[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:
  ```bash theme={null}
  # 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:**

  <Steps>
    <Step title="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:

      ```json .hprc theme={null}
      { "serviceId": "billing-api" }
      ```

      ```typescript src/app.ts theme={null}
      HyperProbe.start({ serviceId: 'billing-api' }); // Must match .hprc!
      ```
    </Step>

    <Step title="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:

      ```bash theme={null}
      curl https://logger.app.hyperprobe.co/health
      ```
    </Step>

    <Step title="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.
    </Step>
  </Steps>

***

### 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:
  ```typescript theme={null}
  HyperProbe.start({
    // ...
    brokerUrl: 'http://host.docker.internal:3001' // Routes to your machine's host localhost!
  });
  ```

***

## ❓ Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Does attaching HyperProbe slow down my production service?">
    No. Unlike traditional debuggers that lock threads or pause execution loops, HyperProbe runs fully asynchronously. It connects non-blocking callbacks to the native runtime engine (V8 Inspector/JVM transformation) that complete inside **microseconds**.

    If the agent ever registers event loop lag crossing your limit (default: 50ms), it automatically activates its **cooldown shield**, instantly unregistering all probes to protect host resource health.
  </Accordion>

  <Accordion title="How does the agent handle sensitive data or compliance?">
    HyperProbe uses **in-process redaction**. Match lists (`password`, `secret`, `token`, `cookie`) are sanitized **inside your container** before any payload is compiled or sent. Plaintext credentials never touch network ports.
  </Accordion>

  <Accordion title="Can I use HyperProbe without TypeScript source maps?">
    Yes, if your code executes directly without transpilations (e.g. standard ES6 Node.js). If you use TypeScript, Babel, Esbuild, or Webpack, **source maps are strictly required** for the agent to match your source files back to compiled JS on disk.
  </Accordion>

  <Accordion title="How do I enable deep debug logs for the SDK?">
    HyperProbe utilizes standard namespace debug log flags. Export the `DEBUG` flag before launching your service to isolate issues:

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>