Handle errors

Overview

When an error occurs in a form flow, an error message is displayed to the user.

This document explains how error handling works in Fortified ID Forms and how you can customize error messages to fit your requirements and user experience.

Default behavior

By default, a popup notification is shown whenever a step in the flow fails.

Both the content and behavior of this error message can be customized using translation keys and configuration settings in your Forms project.

The default translations can be customized by the following translation keys

{
  "forms.retry.title": "An error occurred",
  "forms.retry.description": "Correct the information and submit again.",
  "forms.retry.error": "An error occurred during processing.",
  "forms.retry.button": "Close and correct",
  "forms.retry.restart": "Start over from beginning"
}

Handling errors with FlowFail valve

If a pipe fails due to a FlowFail configuration, the error message is resolved using the configured translation keys.

The system will attempt to find a translation matching the FlowFail key.

If no matching translation is found, the default key forms.retry.error is used instead.

Note: The message from will ALWAYS pass thru the translation.

Configuration

FlowFail valve

{
  "name": "FlowFail",
  "config": {
    "message": "demo.step1.failed_pipe"
  }
}

Translation

{
  "demo.step1.failed_pipe": "Custom message from FlowFail"
}

Customize message from all other valves

All other errors that are not triggered by FlowFail are handled through the Forms configuration under Retry Notification, mentioned in Forms/Key components/Step/Retry Notification. .

This allows you to define custom patterns and translation keys for different error scenarios, enabling more descriptive and user-friendly error messages.

Configuration

Logfile

2026-01-09 10:30:48,090 [PipeExecutor] DEBUG: pipe=step_20251105_110822_pipe Executing valve: ValidateOtp[1] | HI4jMCxD
2026-01-09 10:30:48,090 [PipeModule] DEBUG: pipe=step_20251105_110822_pipe Pipe execution error: User not found in configured parameter. (2 ms) | HI4jMCxD
java.lang.RuntimeException: User not found in configured parameter.
	at foss.pipes.valves.otp.OtpValidationValve.executeItems(OtpValidationValve.java:59)
	at foss.pipes.valves.item.api.AbstractItemValve.execute(AbstractItemValve.java:58)
	at foss.pipes.core.PipeExecutor.iter(PipeExecutor.java:49)
	at foss.pipes.core.PipeExecutor.lambda$iter$1(PipeExecutor.java:56)
2026-01-09 10:30:48,091 [RetryNotification] DEBUG: Retry notification config: {
  "error_mappings" : [ {
    "pattern" : ".*User not found in configured.*",
    "message" : "error.otp_validation1"
  } ]
}
2026-01-09 10:30:48,092 [RetryNotification] DEBUG: Registered error mapping: pattern='.*User not found in configured.*' -> message='error.otp_validation1'
2026-01-09 10:30:48,092 [RetryNotification] DEBUG: Mapped error message 'Pipe failure: step_20251105_110822_pipe (User not found in configured parameter.)' to key 'error.otp_validation1' using pattern '.*User not found in configured.*'
2026-01-09 10:30:48,092 [StepHandler] DEBUG: Mapped exception message to language key: error.otp_validation1
2026-01-09 10:30:48,093 [StepHandler] DEBUG: Pipe failed, setting retry notification state. Error: error.otp_validation1 | HI4jMCxD
2026-01-09 10:30:48,094 [StepHandler] DEBUG: Retry notification sent, preserving step state for retry | HI4jMCxD

Translations

{
  "error.otp_validation1": "Custom message from OTP-Validation"
}

Retry notification

  "retry_notification": {
    "error_mappings": [
      {
        "pattern": ".*User not found in configured.*",
        "message": "error.otp_validation1"
      }
    ]
  }