Error Handling Patterns: From Exception Types to Production Logging

OutSystems has a hierarchy of exception types. Handlers are matched from most specific to least specific: 1. User Exception — custom business exceptions you define and raise with the Raise Exception node. Example: 'InvalidOrderAmount', 'CustomerBlocked'. 2. Database Exception — database constraint violations (FK violation, unique index, NOT NULL breach), connection errors. Triggered automatically by the platform. 3. Communication Exception — network failures when calling REST/SOAP APIs, server timeouts, unreachable servers. 4. Security Exception — unauthorized access, role check failures, invalid sessions. 5. AllExceptions — catches anything not caught by a more specific handler above it. Best practice: always handle the most specific type you expect, then add an AllExceptions handler as a safety net. Handling AllExceptions alone swallows Database and Communication exceptions without distinguishing them. To define a custom User Exception: Logic tab → Exceptions → right-click → Add Exception. Name it (e.g. 'InvalidAmount'). Set BuiltIn = No.

Open SaveEmployee Server Action in the Action Flow Editor (Logic tab → Server Actions → double-click). Right-click any node in the flow (e.g., the CreateEmployee entity action) → 'Add Exception Handler'. A handler connector appears from the node to an Exception Handler node at the bottom of the flow. In the Exception Handler node Properties Panel, set: - Exception: Database Exception - Abort Transaction: Yes (rolls back any uncommitted DB changes) Inside the handler: Start (handler) → LogError ('SaveEmployee failed', ExceptionMessage) → Raise User Exception 'SaveFailed' with message 'Employee could not be saved. Please try again.' → End By raising a User Exception from inside the handler, you convert a technical Database Exception into a business-level exception that the Client Action above can catch with a friendly message.

1/* Exception handler flow inside SaveEmployee */
2Exception Handler (Database Exception, Abort: Yes)
3  --> LogError:
4        ModuleName = "HRModule"
5        Source     = "SaveEmployee"
6        Message    = "DB error saving employee: " + ExceptionMessage
7  --> Raise Exception: SaveFailed
8        Message = "Employee could not be saved. Please try again."
9  --> End

In the Client Action that calls SaveEmployee (e.g., SubmitFormOnClick), add an exception handler for the SaveFailed User Exception. In the Client Action flow, right-click the SaveEmployee call node → 'Add Exception Handler'. Set Exception = SaveFailed (User Exception). Inside the handler: Exception Handler (SaveFailed) --> Message: ExceptionMessage (Warning type) --> End (flow ends here, not navigating away) The ExceptionMessage variable is automatically available inside exception handlers — it holds the message string from the Raise Exception node. For handling all unexpected errors, add a second handler: right-click anywhere in the flow → 'Add Exception Handler' → set to AllExceptions. This catches anything SaveEmployee did not already handle.

1/* Client Action: SubmitFormOnClick */
2Start
3  --> SaveEmployee: FullName, DepartmentId
4  --> Destination: EmployeeListScreen
5  --> End
6
7/* Exception handler attached to SaveEmployee node: */
8Exception Handler (User Exception: SaveFailed)
9  --> Message: ExceptionMessage (MessageType = Warning)
10  --> End
11
12/* Fallback: */
13Exception Handler (AllExceptions)
14  --> Message: "An unexpected error occurred. Our team has been notified." (Error)
15  --> End

OutSystems provides two built-in logging actions in Logic tab → System: - LogMessage(ModuleName, Source, Message): writes to the General log in Service Center. Use for informational events and warnings. - LogError(ModuleName, Source, Message, AdditionalData): writes to the Error log with full stack trace context. Use for all caught exceptions. To use LogError: drag it from Logic tab → System → Logging into the exception handler flow before re-raising or showing the message to the user. In Service Center: Monitoring → Error Logs (shows LogError entries) or Monitoring → General Logs (shows LogMessage entries). Each entry includes timestamp, module, user, environment, and message. Best practice log format: Module='HRModule', Source='SaveEmployee', Message='DB exception: ' + ExceptionMessage + ' | UserId: ' + IntegerToText(GetUserId()) + ' | Input: ' + FullName

1/* LogError call inside exception handler */
2LogError:
3  ModuleName     = "HRModule"
4  Source         = "SaveEmployee"
5  Message        = "DB exception saving employee"
6  AdditionalData = "User: " + IntegerToText(GetUserId())
7                 + " | Name: " + FullName
8                 + " | Error: " + ExceptionMessage

For errors that escape all local handlers (e.g., an unhandled exception in a screen's OnInitialize action), OutSystems redirects to a default error page. You can customize this. In the Interface tab, create a new Screen named 'GlobalErrorScreen'. Set its Role access to Anonymous so any user can see it. In Service Studio: Logic tab → Exceptions → set the Error Handler property of your module to GlobalErrorScreen. Alternatively, in the Interface tab select your UI Flow → Properties Panel → set Error Handler to GlobalErrorScreen. Any unhandled exception in screens within that UI Flow will redirect here. On GlobalErrorScreen: show a user-friendly message ('Something went wrong. Please go back or contact support.') and a button to navigate to Home. Do NOT display the raw ExceptionMessage on this screen — it exposes internal details.