{"record":{"id":"9af54d8d1f3eab4c","repo":"koala73/worldmonitor","slug":"tool-failure-messages-name","errorCode":null,"errorMessage":"${TOOL_FAILURE_MESSAGES[name]}","messagePattern":"\\$\\{TOOL_FAILURE_MESSAGES\\[name\\]\\}","errorType":"error_code","errorClass":"SafeWebMcpError","httpStatus":null,"severity":"error","filePath":"src/services/webmcp.ts","lineNumber":788,"sourceCode":"        outcome: 'failure',\n        reason,\n      });\n      if (signal?.aborted) throwIfWebMcpAborted(signal);\n      if (error instanceof SafeWebMcpError) throw error;\n      if (isWebMcpAbortError(error)) throw error;\n      if (error instanceof DashboardBindingError) {\n        throw new SafeWebMcpError(\n          `Dashboard unavailable: ${boundedText(error.message, 160)} Reason: ${error.reason}.`,\n          'unavailable',\n        );\n      }\n      if (error instanceof DashboardPanelCatalogError) {\n        throw new SafeWebMcpError(error.message, 'validation');\n      }\n      if (error instanceof MissionPresetCatalogError) {\n        throw new SafeWebMcpError(error.message, 'validation');\n      }\n      throw new SafeWebMcpError(TOOL_FAILURE_MESSAGES[name]);\n    }\n  };\n}\n\nfunction enforceOutputBudget(value: unknown): void {\n  const serialized = JSON.stringify(value);\n  if (typeof serialized !== 'string' || serialized.length > MAX_OUTPUT_CHARS) {\n    throw new SafeWebMcpError('Tool output exceeded the safe output limit.');\n  }\n}\n\nfunction structuredResultReasons(result: Record<string, unknown>): string[] {\n  const reasons = typeof result.reason === 'string' ? [result.reason] : [];\n  if (!Array.isArray(result.targets)) return reasons;\n  for (const target of result.targets) {\n    if (target && typeof target === 'object' && 'reason' in target) {\n      const reason = (target as { reason?: unknown }).reason;\n      if (typeof reason === 'string') reasons.push(reason);","sourceCodeStart":770,"sourceCodeEnd":806,"githubUrl":"https://github.com/koala73/worldmonitor/blob/9361220cc013571781071f0206e4d80fd14b2f7f/src/services/webmcp.ts#L770-L806","documentation":"The final fallback in withInvocationLogging: any error thrown by a tool that is not a SafeWebMcpError, DashboardUnavailableError, DashboardPanelCatalogError, or MissionPresetCatalogError is replaced with a generic per-tool message from TOOL_FAILURE_MESSAGES (e.g. 'World Monitor could not switch monitors.'). The original error details are deliberately suppressed so raw internals never leak to the MCP client; analytics still record the true reason.","triggerScenarios":"Any unexpected exception inside a tool handler — a null dereference while reading dashboard state, an unhandled DOM/map error, a bug in applyDashboardAction, or any thrown non-catalog error not classified by the preceding instanceof checks.","commonSituations":"Dashboard DOM not in the expected state when a tool mutates it; race between UI updates and tool execution; bugs introduced by dashboard updates breaking a tool; client calling a tool while the map or panels are in a transient state.","solutions":["Check browser devtools console / WebMCP analytics logs — the generic message hides the real error, which is logged there (classifyInvocationError / trackEvent).","Re-run the tool after the dashboard is idle (no in-flight animations or pending mutations).","Reproduce with the same arguments and file a bug with the tool name and args; a fallback message means an unhandled internal error.","Upgrade WorldMonitor — many internal failures are fixed in later dashboard releases."],"exampleFix":"// before\nawait tools.call('move_panel', { id: 'x', direction: 'left' }); // generic failure, no detail\n// after\ntry {\n  await tools.call('move_panel', { id: 'x', direction: 'left' });\n} catch (e) {\n  console.error('move_panel failed:', e.message); // inspect console + analytics for real cause\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isGenericToolFailure(e) {\n  return e instanceof Error && /^World Monitor could not /.test(e.message);\n}","tryCatchPattern":"try {\n  return await tools.call(name, args);\n} catch (e) {\n  if (isGenericToolFailure(e)) {\n    console.error(`tool ${name} failed internally with args`, args, e.message);\n    // check analytics/devtools console for the suppressed root cause\n  }\n  throw e;\n}","preventionTips":["Treat this generic message as a signal to inspect console/analytics, since the root cause is hidden.","Avoid calling mutating tools while the dashboard is mid-animation or mid-update.","Keep WorldMonitor and your integration on matching versions.","Capture tool name + args in your own logging to aid bug reports."],"tags":["webmcp","internal-error","fallback","unhandled-exception"],"backgroundTag":"unhandled-tool-exception","analyzedSha":"9361220cc013571781071f0206e4d80fd14b2f7f","analyzedAt":"2026-09-01T10:32:37.851Z","contentChangedAt":"2026-09-01T10:32:37.851Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}