# Reported issues for NEAT

Pod holds 24 of 81 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [NEAT](/mcp/neat).

## Most discussed

### (Pilot 1) OBSERVED connectors load and validate but never poll (idle forever, no trigger, no logs)

## Summary

After adding OBSERVED connectors (both `supabase` — **validated OK** — and `railway`) to a running project, the daemon loads them but **never polls them**. `GET /connectors` reports both stuck at `state: "idle"`, `lastPollAt: null`, `signalsLastPoll: 0` for the entire daemon lifetime (observed **7+ minutes undisturbed**, a 15-minute watch in progress). No OBSERVED edges are minted, nothing is logged to stdout or `neat-out/errors.ndjson`, and there is **no operator-facing way to trigg

[Read the thread](https://github.com/neat-technologies/neat/issues/871) · 2026-07-24 · closed · outside contributor · 3 comments

### (Pilot 1) Railway connector: auth-check rejects a fully-authorized account token with "Not Authorized"

## Summary

`neat connector add railway` (v0.6.1) rejects a **valid, fully-authorized Railway account token** with:

```
railway auth check failed: Railway GraphQL errors: Not Authorized
```

and refuses to store the connector. The **same token** successfully runs every Railway GraphQL query the connector needs — including the observability queries (`deploymentLogs`, `httpLogs`, `metrics`) — when called directly against `https://backboard.railway.com/graphql/v2`. So the credential is good; NEAT'

[Read the thread](https://github.com/neat-technologies/neat/issues/868) · 2026-07-24 · closed · outside contributor · 2 comments

### Vercel edge-runtime instrumentation — debug + harden against a real deployment (owner: Jed)

**Owner: Jed** · **Vercel edge-runtime instrumentation** (ADR-126, first exception to `framework-installers.md` §6)

Goal: **debug the Vercel edge instrumentation against a real deployment, then make it robust.** ⚠️ **Vercel is not a pull-connector** — there is no `neat connector add vercel`. It's an **installer path**: NEAT generates edge-runtime OTel instrumentation that rides the existing OTLP push. Your scope is that installer + the edge spans it produces, end to end on a real Vercel deploym

[Read the thread](https://github.com/neat-technologies/neat/issues/740) · 2026-07-08 · closed · outside contributor · 2 comments

### Make get_dependencies transitive

**Source:** Verification pass — MCP audit §6. `docs/audits/verification.md`.

`get_dependencies` (`packages/mcp/src/tools.ts:143-156`) returns only direct outbound edges from `/graph/edges/{id}`. The audit expects transitive dependencies — Claude Code's "what does this service end up touching" question is rarely satisfied by one hop.

**Fix shape:** new core endpoint `GET /graph/node/:id/dependencies?depth=N` that BFS-walks outbound edges (not just CALLS — also CONNECTS_TO and DEPENDS_ON). Defau

[Read the thread](https://github.com/neat-technologies/neat/issues/144) · 2026-05-04 · closed · outside contributor · 2 comments

### MCP tools: emit standardized three-part response (NL paragraph + structured block + footer)

**Source:** Verification pass — MCP audit §3. `docs/audits/verification.md`.

The MCP audit specifies a three-part response format for every tool:

1. **NL paragraph** — actionable, human-readable summary of what the tool found.
2. **Structured block** — the typed payload (path, distances, provenance per edge).
3. **Footer line** — `confidence: X.XX · provenance: OBSERVED|EXTRACTED|...`.

Today's tools (`packages/mcp/src/tools.ts`) emit a header + bullet list — no NL paragraph for blast-radius/d

[Read the thread](https://github.com/neat-technologies/neat/issues/143) · 2026-05-04 · closed · outside contributor · 2 comments

### Add path and confidence fields to BlastRadiusAffectedNode

**Source:** Verification pass — Types audit §8, Traversal audit §6. `docs/audits/verification.md`.

`BlastRadiusAffectedNode` in `packages/types/src/results.ts:14-18` has `nodeId`, `distance`, `edgeProvenance`. The audit contract requires:

- `path: string[]` — node IDs from origin to this node
- `confidence: number` — cascaded confidence of this path

Both are computable in `getBlastRadius` (we already track parents in the BFS frame and have `confidenceFromMix` for cascading). Today they're com

[Read the thread](https://github.com/neat-technologies/neat/issues/137) · 2026-05-04 · closed · outside contributor · 2 comments

### Auto-create ServiceNode and DatabaseNode from OTel spans alone

**Source:** Verification pass — OTel audit §3, §5. `docs/audits/verification.md`.

`handleSpan` in `packages/core/src/ingest.ts:311-376` never calls `addNode` for `service:${span.service}`. If the service was not extracted statically, `upsertObservedEdge` returns null at `ingest.ts:207` because the source node is missing. Same for `database:${host}`: DBs only get OTel-driven CONNECTS_TO edges if a static DatabaseNode at that id already exists (`ingest.ts:318-332`).

This is a **critical gap for 

[Read the thread](https://github.com/neat-technologies/neat/issues/134) · 2026-05-04 · closed · outside contributor · 2 comments

### Generalize getRootCause beyond DatabaseNode origins (driver/engine compat is the only matrix shape today)

\`packages/core/src/traverse.ts:185\` short-circuits when the origin isn't a \`DatabaseNode\`:

\`\`\`ts
if (startAttrs.type !== NodeType.DatabaseNode) return null
\`\`\`

Documented inline as \"driver/engine mismatches are still the only shape the compat matrix describes.\" That was true through v0.1.2 — the matrix only carried (driver, engine) pairs. γ #74 grew it to four kinds (\`driver-engine\`, \`node-engine\`, \`package-conflict\`, \`deprecated-api\`), but the traversal entry point still r

[Read the thread](https://github.com/neat-technologies/neat/issues/123) · 2026-05-04 · closed · outside contributor · 2 comments

## Most recent

### Connector-sourced incidents don't fire the incident push event (no project at appendConnectorIncident)

## What

ADR-221 (the incident card, PR #1105) added a ninth SSE event type `incident` that the monitor and `get_incident_card` consumers react to. The event is emitted from the OTel incident write paths in `ingest.ts` (`appendErrorEvent` / `makeErrorSpanWriter`), which have the project name in scope.

Connector-sourced incidents take a different write path — `appendConnectorIncident` (ADR-185, the `errorType: 'http-failure'` build/poll failures) — and that call site does not carry a project nam

[Read the thread](https://github.com/neat-technologies/neat/issues/1106) · 2026-08-29 · open · outside contributor · 0 comments

### Push a self-sufficient incident work order to the agent (the incident goodybag)

## What

When an incident fires, an agent should be handed a single, self-sufficient work order — the "goodybag" — so it can start writing the fix without grepping or guessing. Today the pieces exist but nobody composes them and nothing pushes them: `get_root_cause`, `get_blast_radius`, `check_policies`, and `get_divergences` are all pull-only, and `neat monitor` (ADR-159) streams divergence/stale/observed/policy facts but has no incident fact kind.

## The goodybag

One card, composed from quer

[Read the thread](https://github.com/neat-technologies/neat/issues/1104) · 2026-08-29 · open · outside contributor · 0 comments

### Empty MCP results should say whether the index is still building

An empty query result on the MCP surface is ambiguous. When a tool comes back with "no such edges" / "no dependencies" / "no divergences" / "node not found", an agent can't tell a genuinely-empty answer apart from a graph that hasn't finished its first extraction pass yet. NEAT's own MCP instructions already tell the agent to "confirm the daemon is up if a query comes back empty" — but that check belongs in the response, not the docs.

A dead daemon is already unambiguous: `cli-client.ts` raises

[Read the thread](https://github.com/neat-technologies/neat/issues/1101) · 2026-08-28 · open · outside contributor · 0 comments

### neat doctor: a preflight diagnostic for setup

Getting NEAT running is a few separate steps — the right Node, the daemon, a project registered for this directory — and when one of them isn't in place, nothing points at which one. A query just comes back unreachable, or the CLI fails in a way that doesn't name the cause. Our own MCP instructions already lean on "if a query comes back empty, confirm the daemon is up," which is exactly the check a person shouldn't have to run by hand.

`neat doctor` gives one command that probes the setup and p

[Read the thread](https://github.com/neat-technologies/neat/issues/1094) · 2026-08-25 · open · outside contributor · 0 comments

### MCP server: confusing HTML-404 when the localhost:8080 fallback hits a non-NEAT service

## What

The MCP server resolves the core REST URL by walking up from its CWD for `neat-out/daemon.json` (good — picks up the real port), with `NEAT_CORE_URL`/`NEAT_API_URL` overriding. When neither a `daemon.json` (upward from the MCP server's CWD) nor an env override is found, it falls back to `http://localhost:8080` (`packages/mcp/src/base-url.ts:21`).

The papercut: if something **other than a NEAT daemon** is listening on 8080, the MCP tools silently talk to it and surface its response. In 

[Read the thread](https://github.com/neat-technologies/neat/issues/1069) · 2026-08-20 · open · outside contributor · 0 comments

### OTLP/HTTP receiver rejects gzip-compressed request bodies (400 FST_ERR_CTP_INVALID_CONTENT_LENGTH)

## What

NEAT's OTLP/HTTP trace receiver (`:4319/v1/traces`) returns **HTTP 400** on any gzip-compressed request body:

```
{"statusCode":400,"code":"FST_ERR_CTP_INVALID_CONTENT_LENGTH","error":"Bad Request"}
```

The Fastify receiver reads the raw body and does not honor `Content-Encoding: gzip`, so a compressed payload fails content-length validation.

## Why it matters

The **OpenTelemetry Collector's `otlphttp` exporter gzips by default** (`compression: gzip`). So a standard, unmodified coll

[Read the thread](https://github.com/neat-technologies/neat/issues/1068) · 2026-08-20 · open · outside contributor · 0 comments

### SEP-414 trace context: SPIKE the agent-to-app trace join before wiring it

## The differentiator — but verify what actually joins FIRST

SEP-414 fixes `traceparent`/`tracestate`/`baggage` in `_meta` on every request. NEAT is the only tool in our set that speaks MCP AND ingests OTel AND has a code graph. Pitch: follow the trace from the agent's tool call into what the code actually did.

## The caveat that decides if it's real (correct, from the briefing)
The MCP trace id correlates the agent's call with spans **the MCP server itself makes**. A separately-instrumented a

[Read the thread](https://github.com/neat-technologies/neat/issues/1058) · 2026-08-20 · open · outside contributor · 0 comments

### Migrate @neat.is/mcp to the 2026-07-28 MCP spec (stateless core + breaking changes)

## Compliance — mandatory, our server targets the old lifecycle

The 2026-07-28 MCP spec is FINAL and carries breaking changes. Clients will move; a non-compliant server gets dropped. Audit `@neat.is/mcp` against all of it:

- [ ] **Stateless core (SEP-2575, SEP-2567)** — `initialize`/`initialized` handshake removed; `Mcp-Session-Id` + protocol-level session removed; protocol version + client info + capabilities now travel in `_meta` on every request; new `server/discover` method for capabilitie

[Read the thread](https://github.com/neat-technologies/neat/issues/1057) · 2026-08-19 · open · outside contributor · 0 comments

### get_root_cause dead-ends on STALE-only upstream — hands the agent the symptom, not the cause

## Found by the ±NEAT RCA benchmark (S24 / ITBench)

The neat-assisted arm mis-rooted an incident because `get_root_cause` refused to traverse a causal chain that exists but is STALE.

**What NEAT returned to the agent:**
- `ask "why is frontend-proxy erroring"` → "Root cause: **service:frontend** — 92 gRPC INTERNAL incidents" (the *symptom* node)
- `get_root_cause(service:frontend)` → "root cause is service:frontend... Traversal path: service:frontend. Edge provenances: (direct, no edges traver

[Read the thread](https://github.com/neat-technologies/neat/issues/1050) · 2026-08-19 · open · outside contributor · 0 comments

### A plain-language door into the graph: neat ask + a query-first directive

NEAT's tools are structured — you have to know which one (`get_root_cause`, `get_dependencies`, `get_blast_radius`) and the exact node id before you can call it. That's more friction than `grep`, so in practice an agent falls back to reading source instead of reaching for the graph, even when the graph would answer better. A benchmark run showed exactly this: on a legible scenario the agent solved it by grepping and never touched NEAT.

The fix is to make the graph lower friction than grep, in t

[Read the thread](https://github.com/neat-technologies/neat/issues/1027) · 2026-08-17 · open · outside contributor · 0 comments

### EAS build-failure connector — pull ERRORED builds, mint commit-grain OBSERVED incidents on the repo (phase-mapped)

Pull `ERRORED` EAS builds from the Expo GraphQL API and mint OBSERVED build-failure incidents anchored to the commit (`gitCommitHash`) and — where `error.buildPhase` allows — the specific repo node that failed, so an agent can query `get_incident_history`/`get_root_cause` and fix it in the repo. This is the root-cause query applied to the CI-build domain; the join back to source is exact (commit hash), so it fuses rather than sitting as static config.

**v1 = phase-mapped** (chosen scope). `erro

[Read the thread](https://github.com/neat-technologies/neat/issues/996) · 2026-08-13 · closed · outside contributor · 1 comment

### Add `neat opencode` / `neat crush` install verbs (ADR-172 second wave)

ADR-172 shipped one-command MCP installs for `neat gemini` / `qwen` / `amazonq` / `roocode` / `zed`, and named the two terminal agents it deliberately held back: OpenCode and Crush. Both keep a stable, documented config file, but describe an stdio MCP server with a different server-object shape than the flat `{command, args}` the shipped verbs write — so ADR-172 left them for a follow-on. This is that follow-on.

## The two verified surfaces (Aug 2026)

**OpenCode** — `~/.config/opencode/opencod

[Read the thread](https://github.com/neat-technologies/neat/issues/965) · 2026-08-09 · closed · outside contributor · 1 comment

### Onboard NEAT into the GitHub MCP Registry (partnerships@github.com)

The GitHub MCP Registry (github.com/mcp) powers VS Code's in-editor `@mcp` gallery and Copilot discovery. It is **separate** from the official modelcontextprotocol registry — being in the official one (which NEAT is) does **not** auto-list us here; it only enables version-sync **after** GitHub onboards the server.

**Why a human:** onboarding is manual curation, not self-serve — a BD email from a company address. No code.

**Steps:**
1. Confirm NEAT still resolves in the official registry:
   `c

[Read the thread](https://github.com/neat-technologies/neat/issues/955) · 2026-08-08 · open · outside contributor · 0 comments

### @neat.is/mcp ships with no README; add an agent-install guide

The `@neat.is/mcp` package has no `README.md`, so its npm page is blank — a poor first impression for the one package agents install by name, and nothing for a marketplace reviewer (Cline etc.) to follow.

Two additive docs:
- **`packages/mcp/README.md`** — what the server is (a stdio bridge to a running NEAT daemon, not a standalone server), the daemon prerequisite, how to wire it into an MCP client (`npx -y @neat.is/mcp` / `neat-mcp` / `NEAT_CORE_URL`), how it resolves the daemon URL, and the 

[Read the thread](https://github.com/neat-technologies/neat/issues/951) · 2026-08-07 · closed · outside contributor · 1 comment

### field-guard policy — flag Firestore fields the code writes but firestore.rules doesn't guard

Catch the silent footgun: a change adds a privileged field on the write path, and the security-rules denylist the dashboard trusts never covered it, so the field is silently client-writable. Surface it as a policy check on the PR.

## Goal
- New producer parsing `firestore.rules` as a declared artifact → a guarded-field set per collection, attached to the `firestore-collection` node (distinct from its written `columns`). Extracting structure from a checked-in policy file, not snapshotting secret

[Read the thread](https://github.com/neat-technologies/neat/issues/941) · 2026-08-05 · closed · outside contributor · 1 comment

### neat cursor + neat windsurf — one-command install NEAT into the VS Code MCP family (ADR-164)

Ubiquity/distribution sibling of the Codex install. `neat cursor --apply` / `neat windsurf --apply` wire NEAT's MCP server (`npx -y @neat.is/mcp`) into the client's JSON MCP config (Cursor `~/.cursor/mcp.json` / project `.cursor/mcp.json` `mcpServers`; Windsurf `~/.codeium/windsurf/mcp_config.json`) and the graph-first guidance (`GRAPH_FIRST.md`) into the client's rules file (`.cursorrules` / Windsurf rules), mirroring `neat skill`/`neat hooks`: plan-by-default, `--apply`, idempotent, additive. 

[Read the thread](https://github.com/neat-technologies/neat/issues/933) · 2026-08-05 · closed · outside contributor · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/NEAT-Technologies/Neat/issues).