{"record":{"id":"945ab2ecb34afa44","repo":"Egonex-AI/Understand-Anything","slug":"freshness-response-was-malformed","errorCode":null,"errorMessage":"Freshness response was malformed","messagePattern":"Freshness response was malformed","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"understand-anything-plugin/packages/dashboard/src/freshness.ts","lineNumber":177,"sourceCode":"\nexport function shouldRequestFreshness(\n  demoMode: boolean,\n  demoFreshnessUrl?: string,\n): boolean {\n  return !demoMode || Boolean(demoFreshnessUrl);\n}\n\nexport async function requestFreshnessReport(\n  url: string,\n  signal: AbortSignal,\n  fetcher: typeof fetch = fetch,\n): Promise<DashboardFreshnessReport> {\n  const response = await fetcher(url, { signal, cache: \"no-store\" });\n  if (!response.ok) throw new Error(\"Freshness request failed\");\n\n  const payload: unknown = await response.json();\n  if (!isDashboardFreshnessReport(payload)) {\n    throw new Error(\"Freshness response was malformed\");\n  }\n  return payload;\n}\n\ninterface FreshnessRefreshOptions {\n  target: Pick<EventTarget, \"addEventListener\" | \"removeEventListener\">;\n  load: (signal: AbortSignal) => Promise<DashboardFreshnessReport>;\n  onResult: (report: DashboardFreshnessReport) => void;\n}\n\nfunction requestFailedReport(): DashboardFreshnessReport {\n  return {\n    graphs: {\n      knowledge: {\n        status: \"unknown\",\n        reason: \"freshness-request-failed\",\n      },\n    },","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/32944829e7a63a9fa9c55d811d7f98a9530c6a6a/understand-anything-plugin/packages/dashboard/src/freshness.ts#L159-L195","documentation":"Thrown by requestFreshnessReport after a successful HTTP response whose JSON body fails the isDashboardFreshnessReport structural guard. The guard verifies a graphs object with a valid knowledge GraphFreshnessResult and an optional domain result, each of which must match one of the status variants (fresh/dirty/stale/unknown) with consistent counts and hashes.","triggerScenarios":"The freshness endpoint returns 200 but the body is not the expected shape: missing graphs, a knowledge result with an unknown status string, mismatched changedFileCount vs changedFiles.length, a non-hash graphCommitHash, or a stale result lacking a valid relation. Also fires on an unrelated 200 response (e.g. an HTML page from a misrouted proxy).","commonSituations":"Tool/dashboard version skew where the server emits a newer or older freshness schema; a proxy intercepting and returning a different 200 body; a half-deployed backend; a hand-crafted freshness endpoint that omits required fields.","solutions":["Confirm the dashboard dev server version matches the client expecting this freshness schema.","Inspect the actual response body to find which field the isDashboardFreshnessReport guard rejects (status string, count consistency, hash format, relation).","Ensure the freshness endpoint returns a complete DashboardFreshnessReport with valid knowledge (and optional domain) results.","Handle the error and fall back to the degraded 'unknown' report, as startFreshnessRefresh does."],"exampleFix":"// before\nconst report = await requestFreshnessReport(url, signal);\n// after — guard then degrade\nimport { isDashboardFreshnessReport } from './freshness';\nconst payload = await (await fetch(url)).json();\nconst report = isDashboardFreshnessReport(payload) ? payload : { graphs: { knowledge: { status: 'unknown', reason: 'freshness-request-failed' } } };","handlingStrategy":"type-guard","validationCode":"import { isDashboardFreshnessReport } from './freshness';\nconst payload = await (await fetch(url)).json();\nif (!isDashboardFreshnessReport(payload)) { /* use degraded report instead of throwing */ }","typeGuard":"import { isDashboardFreshnessReport, type DashboardFreshnessReport } from './freshness';\n// isDashboardFreshnessReport is the exported type guard:\n// (value: unknown) => value is DashboardFreshnessReport","tryCatchPattern":"let report: DashboardFreshnessReport;\ntry { report = await requestFreshnessReport(url, signal); }\ncatch (e) { report = { graphs: { knowledge: { status: 'unknown', reason: 'freshness-request-failed' } } }; }","preventionTips":["Always go through startFreshnessRefresh so a malformed response degrades gracefully.","Keep server and client freshness schemas in lockstep.","Pre-validate the body with isDashboardFreshnessReport before trusting it."],"tags":["dashboard","validation","type-guard","freshness"],"backgroundTag":null,"analyzedSha":"32944829e7a63a9fa9c55d811d7f98a9530c6a6a","analyzedAt":"2026-08-12T10:25:44.261Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}