Egonex-AI/Understand-Anything · error · Error

HTTP ${res.status}

Error message

HTTP ${res.status}

What it means

Thrown by the dashboard's knowledge-graph loader in App.tsx when fetch(dataUrl('knowledge-graph.json', accessToken)) returns a non-ok response. The guard runs before res.json() so that a 404/500 JSON error body is not silently fed into validateGraph (which would otherwise surface the misleading 'Invalid knowledge graph: Missing or invalid project metadata'). It prefers body.error when the server provides one, falling back to `HTTP <status>`.

Source

Thrown at understand-anything-plugin/packages/dashboard/src/App.tsx:162

  useEffect(() => {
    fetch(dataUrl("knowledge-graph.json", accessToken))
      .then(async (res) => {
        // Guard res.ok before parsing (matching the meta.json/config.json/
        // diff-overlay.json/domain-graph.json fetches in this file). Without
        // this, a serving/config failure returns a 404 JSON error body that
        // gets parsed and handed to validateGraph, which fails project-metadata
        // validation and surfaces the misleading "Invalid knowledge graph:
        // Missing or invalid project metadata" instead of the real cause
        // (graph file not found / GRAPH_DIR unset). See issues #288, #406.
        if (!res.ok) {
          let detail = `HTTP ${res.status}`;
          try {
            const body = await res.json();
            if (body?.error) detail = body.error;
          } catch {
            /* non-JSON error body; keep the status code */
          }
          throw new Error(detail);
        }
        return res.json();
      })
      .then((data: unknown) => {
        const result = validateGraph(data);
        if (result.success && result.data) {
          setGraph(result.data);
          setGraphIssues(result.issues);
          if ((data as Record<string, unknown>).kind === "knowledge") {
            useDashboardStore.getState().setViewMode("knowledge");
            useDashboardStore.getState().setIsKnowledgeGraph(true);
          }
          for (const issue of result.issues) {
            if (issue.level === "auto-corrected") {
              console.warn(`[graph] auto-corrected: ${issue.message}`);
            } else if (issue.level === "dropped") {
              console.error(`[graph] dropped: ${issue.message}`);
            }

View on GitHub (pinned to 32944829e7)

Solutions

  1. Run /understand (or /understand --full) in the target project so knowledge-graph.json is generated in its .ua/ directory.
  2. Confirm GRAPH_DIR is set for the dev server process and points at the project's .ua/ (or legacy .understand-anything/) directory.
  3. Verify the access token in the browser URL/header matches UA_DASHBOARD_ACCESS_TOKEN on the server.
  4. Open the failing URL directly in the browser to read the server's JSON error body, which often names the missing file or directory.
  5. Check the dev server console for the stack trace that produced the non-200 response.
Defensive patterns

Strategy: try-catch

Validate before calling

// before mounting the dashboard, ensure the graph exists
import { existsSync, statSync } from 'node:fs';
function ensureGraphServed(graphDir) {
  if (!graphDir) throw new Error('GRAPH_DIR env is unset');
  const p = `${graphDir}/knowledge-graph.json`;
  if (!existsSync(p) || !statSync(p).isFile()) {
    throw new Error(`knowledge-graph.json not found at ${p}; run /understand first`);
  }
}

Try / catch

// in the dashboard fetch chain (matches App.tsx pattern)
fetch(dataUrl('knowledge-graph.json', accessToken))
  .then(async (res) => {
    if (!res.ok) {
      let detail = `HTTP ${res.status}`;
      try { const b = await res.json(); if (b?.error) detail = b.error; } catch {}
      throw new Error(detail);
    }
    return res.json();
  })
  .catch((err) => setLoadError(`Failed to load knowledge graph: ${err.message}`));

Prevention

When it happens

Trigger: The dev server returns non-200 for knowledge-graph.json: GRAPH_DIR env unset or pointing at a missing directory (404), the access token is wrong/missing (403), the server is misconfigured (500), or the graph file genuinely does not exist yet because /understand has not been run in the target project.

Common situations: Starting the dashboard before running /understand (no graph generated). GRAPH_DIR not exported in the dev-server environment. Wrong UA_DASHBOARD_ACCESS_TOKEN in the browser vs server. Serving from a different working directory than expected. Reverse proxy / CORS intercepting the request. The graph was moved/deleted out from under the server.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@32944829e7 (2026-08-12). Data as JSON: /api/errors/9e31a14998758ad0. Report an issue: GitHub.