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.

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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 2026-08-05 · closed · outside contributor · 1 comment

The remaining reports are on the project's issue tracker.