Troubleshooting
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:
[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 that
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 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
Does attaching InSitu slow down my production service?
Capture overhead depends on your workload, probe locations, and captured data. Agents include safety limits that can suspend probes when those limits are exceeded. See the
Python SDK guide
for Python behavior.
How does the agent handle sensitive data or compliance?
InSitu applies redaction inside the application process. Coverage depends on your configured key and value patterns and the probe expressions you use. In Python, key patterns do not protect scalar watch results; see the
Python redaction guide
.
Can I use InSitu 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.
How do I enable deep debug logs for the SDK?
InSitu utilizes standard namespace debug log flags. Export the
DEBUG
flag before launching your service to isolate issues:
# 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
Production Safety, Guardrails & Security Compliance
Previous
Self-Hosting Deployment Guide
Next
⌘
I
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform
Terms of Service
On this page
Back to top
🛠️ Step-by-Step Error Resolutions
1. Agent Fails to Start: Missing commitSha
2. Probe Gutter Icon Shows Hollow Orange Dot (Agent Not Going Live)
3. Gutter Gutter Icon Shows Error Status (Solid Red Dot)
4. Local Docker Connection Fails (http://localhost:3001)
❓ Frequently Asked Questions