Troubleshooting Glossary & FAQ

🛠️ Step-by-Step Error Resolutions

1. Agent Fails to Start: Missing commitSha

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

• Cause: InSitu.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 InSitu.start() in your server code:

  .hprc

  { "serviceId": "billing-api" }
  

  src/app.ts

  InSitu.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.useinsitu.com/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 thatdistLocation 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 InSitu 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:
  InSitu.start({
    // ...
    brokerUrl: 'http://host.docker.internal:3001' // Routes to your machine's host localhost!
  });
  

❓ Frequently Asked Questions

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

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