Openspec fails to init when used in a closed enterprise network

[onemorezero]

Openspec init fails when run in a closed enterprise network because an exception occurs when it is sending back metrics using posthog. Could we allow metrics data to be opt-in?

[1code-async]

Task completed.

Let me check what the PostHog Node SDK's shutdown() method does regarding timeouts, and look at the design doc for more context.

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Related Issues

• Opt-out telementry? #486 (closed) — "Opt-out telemetry?" — A user on a company network had their proxy server blocking the telemetry endpoint, causing error logs on every command. They self-resolved by setting OPENSPEC_TELEMETRY=0. This is essentially the same root cause (restricted network blocking https://edge.openspec.dev).

Relevant Code

Telemetry is implemented in src/telemetry/index.ts and integrated via Commander.js hooks in src/cli/index.ts:71-88.

How telemetry fires during init:

1. preAction hook (src/cli/index.ts:71) — Before the init command runs, maybeShowTelemetryNotice() and trackCommand() are called. trackCommand() creates a PostHog client and calls client.capture() which queues a network request.

2. postAction hook (src/cli/index.ts:86) — After init completes, shutdown() is called, which awaits posthogClient.shutdown() to flush pending events (src/telemetry/index.ts:149-161).

The likely failure point: The await posthogClient.shutdown() call at line 155 attempts to flush the pending event to https://edge.openspec.dev. In a closed enterprise network where this host is unreachable, the HTTP request will hang until the PostHog SDK's internal timeout expires. While there is a try/catch around the shutdown call, the await still blocks until the network request times out. The PostHog Node SDK's default requestTimeout is 30 seconds — meaning in a blocked network, the CLI could hang for up to 30 seconds on every command before the timeout fires and the catch block handles it. If the timeout is not configured or the SDK throws before the catch can handle it properly, this could surface as an unhandled exception.

Existing opt-out mechanisms (src/telemetry/index.ts:32-49):

OPENSPEC_TELEMETRY=0   # Explicit opt-out
DO_NOT_TRACK=1         # Industry standard
CI=true                # Auto-disabled in CI

These are environment-variable-only. There is no persistent config-file-based opt-out or CLI command to disable telemetry. The design doc (openspec/changes/archive/2026-01-09-add-posthog-analytics/design.md:42) explicitly noted that a openspec telemetry CLI command was deferred as a future enhancement.

Root Cause

The issue has two aspects:

1. Blocking behavior: shutdown() awaits a network request that will time out in a restricted network, causing the CLI to hang. The PostHog client is created without a requestTimeout option (src/telemetry/index.ts:80-84), so it uses the SDK default (30s).

2. Discoverability of opt-out: The opt-out mechanism exists but is only shown once (first-run notice) and requires setting environment variables. Users in enterprise environments may not see this notice or may not know how to make it persistent.

Suggested Approaches

1. Add a requestTimeout to the PostHog client to reduce hang time in unreachable networks:

   posthogClient = new PostHog(POSTHOG_API_KEY, {
     host: POSTHOG_HOST,
     flushAt: 1,
     flushInterval: 0,
     requestTimeout: 5000, // 5 second timeout instead of 30s default
   });

   File: src/telemetry/index.ts:80-84

2. Add a shutdown() timeout wrapper so the CLI never blocks for more than a few seconds:

   const SHUTDOWN_TIMEOUT_MS = 3000;
   await Promise.race([
     posthogClient.shutdown(),
     new Promise(resolve => setTimeout(resolve, SHUTDOWN_TIMEOUT_MS)),
   ]);

   File: src/telemetry/index.ts:149-161

3. Add a persistent config-based opt-out (e.g., openspec config set telemetry.enabled false or checking a field in ~/.config/openspec/config.json) so enterprise users don't need to configure environment variables in every shell. The config infrastructure already exists in src/telemetry/config.ts.

4. Regarding opt-in vs opt-out: The design doc (openspec/changes/archive/2026-01-09-add-posthog-analytics/design.md:23-36) explains the rationale for opt-out: opt-in typically yields ~3% participation. An intermediate approach could be to auto-detect unreachable networks (e.g., if the first request fails, disable telemetry for the session).

[TabishB]

@onemorezero Telemetry can be opted out as documented here: https://github.com/Fission-AI/OpenSpec?tab=readme-ov-file#other

We respect the DO_NOT_TRACK env var as well. We'll try to get this added to the config for easier persistence as well.

[onemorezero]

Awesome thanks for the help. Can I suggest that the exception should be caught and the error message suggest that this be set?

[chilin0525]

@TabishB Could we consider adding a clearer error message for users, or documenting this in the FAQ?
I ran into the same issue, and OpenSpec crashed directly, which was quite confusing.

[TabishB]

@chilin0525 yep added to look at tomorrow