Principle:Langgenius Dify ErrorHandling
| Knowledge Sources | Dify |
|---|---|
| Domains | Frontend, Error Handling |
| Last Updated | 2026-02-12 07:00 GMT |
Overview
Dify's frontend error handling pattern extracts human-readable error messages from nested backend error structures, particularly the deeply wrapped JSON error responses returned by plugin execution failures.
Description
Backend errors in Dify, especially those originating from plugin execution, arrive in nested structures where the actual error message is embedded within a JSON string inside another error message. A typical plugin error follows the pattern: req_id: xxx PluginInvokeError: {"message":"Bad credentials"}. The parsePluginErrorMessage function (utils/error-parser.ts) handles this unwrapping by first extracting the raw message from either a Response object (cloning and parsing the JSON body) or a plain error object, then applying a regex pattern to locate the PluginInvokeError: marker and parse the embedded JSON to extract the inner message or error_type field.
The parser is designed to be resilient: if the nested JSON fails to parse, it falls back to the raw message. If the error object has no message property, it falls back to toString(). If all else fails, it returns "Unknown error". This defensive approach ensures that error toasts and UI feedback always display something meaningful to the user, even when the error structure is unexpected or malformed.
This error parsing integrates with the broader error handling pipeline in the service layer, where the fetch module's afterResponse hooks catch HTTP error responses and display toast notifications. The error parser adds a specialized layer for plugin-specific errors that would otherwise show opaque serialized JSON to end users.
Usage
Use this principle when:
- Adding error handling for new plugin types or backend services that return nested error structures
- Improving error message presentation in toast notifications or inline error displays
- Implementing error parsing for new error formats introduced by backend changes
Theoretical Basis
This pattern implements the Error Translation principle from distributed systems, where errors from downstream services (plugins) are translated into a format meaningful to the upstream consumer (the UI). The defensive fallback chain follows the Graceful Degradation pattern, ensuring that parsing failures at any level still produce usable output. The regex-based extraction of structured data from unstructured error strings is an application of Message Parsing from messaging system design.