{"title":"Actionable errors","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-actionable-errors/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-actionable-errors, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-actionable-errors","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to write AL code that returns error dialogs where users might unblock themselves.","date":"2026-06-29","meta":{"topic":"overview"},"outline":[{"level":2,"title":"Unblocking users with actionable errors","slug":"unblocking-users-with-actionable-errors","at":334,"chars":1754},{"level":2,"title":" Error messages with Fix-it actions","slug":"error-messages-with-fix-it-actions","at":2088,"chars":3146},{"level":3,"title":"Guidance for button labels for Fix-it actions","slug":"guidance-for-button-labels-for-fix-it-actions","at":2588,"chars":467},{"level":3,"title":"Example (error dialog with a Fix-it action)","slug":"example-error-dialog-with-a-fix-it-action","at":3055,"chars":821},{"level":3,"title":"Example (validation error with a Fix-it action)","slug":"example-validation-error-with-a-fix-it-action","at":3876,"chars":1358},{"level":2,"title":" Error messages with Show-it actions","slug":"error-messages-with-show-it-actions","at":5234,"chars":4701},{"level":3,"title":"Automatic Show-it actions from TestField","slug":"automatic-show-it-actions-from-testfield","at":5818,"chars":1056},{"level":3,"title":"Guidance for button labels for Show-it actions","slug":"guidance-for-button-labels-for-show-it-actions","at":6874,"chars":602},{"level":3,"title":"Example (error dialog with a Show-it action)","slug":"example-error-dialog-with-a-show-it-action","at":7476,"chars":1106},{"level":3,"title":"Example (validation error with one Show-it action)","slug":"example-validation-error-with-one-show-it-action","at":8582,"chars":1353},{"level":2,"title":"Error messages with multiple actions - how to use them?","slug":"error-messages-with-multiple-actions---how-to-use-them","at":9935,"chars":3092},{"level":3,"title":"Example (error dialog with two actions)","slug":"example-error-dialog-with-two-actions","at":10138,"chars":1446},{"level":3,"title":"Example (validation error with two promoted actions)","slug":"example-validation-error-with-two-promoted-actions","at":11584,"chars":1443},{"level":2,"title":"Error messages with no actions (final resort)","slug":"error-messages-with-no-actions-final-resort","at":13027,"chars":939},{"level":2,"title":"Related information","slug":"related-information","at":13966,"chars":298}],"text":"This article describes how to handle error dialogs in AL code, specifically how to use the error handling framework to provide recommended actions to users to resolve errors more effectively.\nFor advice on how to design error dialogs that users understand, see User experience guidelines for errors<devenv-error-handling-guidelines>.\n## Unblocking users with actionable errors\nWith Business Central 2023 release wave 2, the error handling framework has been enhanced to include promoted actions in both error dialogs and validation errors. These promoted actions are designed to assist users in resolving errors more effectively. There are currently two main scenarios to keep in mind when deciding how to use recommended actions:\n devenv-error-handling-guidelines#error-messages-with-fix-it-actions--when-to-use-them actions are recommended for scenarios where the system knows the correct value that should be used to resolve the error.\n devenv-error-handling-guidelines#error-messages-with-show-it-actions--when-to-use-them actions are recommended for scenarios when the system can identify the location where the error may be fixed by the user.\nHere are some quick guidelines on when to use each type of error message and its accompanying recommended actions. However, it's essential to begin by considering whether the error could have been avoided in the first place.\nError type|Description\nTask dialogs|Task dialogs are used when an error can be mitigated by the user choosing between two (sometimes three) different options to continue their task without encountering an error.\nError messages with Fix-it actions<#fix-it-actions>|Fix-it actions can be used when the cause and solution to the error is known and can be solved by users with just one step.\nError messages with Show-it actions<#show-it-actions>|Show-it actions can be used when an error must be corrected on a related table. A Show-it action can then offer a shortcut to the related table, enabling users to correct the error by themselves with one or multiple steps, while keeping the context of their current task.\n##  Error messages with Fix-it actions\nFix-it actions are for when the correct value is known. If all the following four statements are true for your error case, then consider adding a recommended Fix-it action in your error message to enable users to easily unblock themselves from the error.\n1. Is the solution to the error known?\n2. Is the error location on the current page?\n3. Can the error (value) be corrected with one action?\n4. Does the user have permission to make the required correction?\n### Guidance for button labels for Fix-it actions\nTo achieve consistency in the user experience of Fix-it actions, consider following these guidelines for button labels:\n Fix-it actions are often phrased: \"Set value to...\".\n   Such as: \"Set value to 10\", \"Set Status to Open\", or \"Set value to HOME\".\n Fix-it action tooltips are often phrased: \"Sets the value...\".\n Value states are capitalized such as: Yes, Open, Released. Avoid signs for values such as = ,\"\", ().\n### Example (error dialog with a Fix-it action)\nThe following AL code illustrates how to set up an error dialog with a Fix-it action.\n```al\nvar\n    dimension: Text[30];\n    vendorCode: Text[30];\n    FixitErrorInfo: ErrorInfo;\nbegin\n    // setup the error info object\n    FixitErrorInfo.Title('The line dimension value isn''t valid');\n    FixitErrorInfo.Message(\n        StrSubstNo('The dimension value must be blank for the dimension %1 for Vendor %2', dimension, vendorCode)\n    );\n    FixitErrorInfo.DetailedMessage('Add some text to help the person troubleshooting this error.');\n\n    FixitErrorInfo.AddAction(\n        'Set value to blank',\n        Codeunit::FixitCodeunit,\n        FixitCodeunitMethodName\n    );\n\n    Error(FixitErrorInfo);\nend\n```\nIf the user experience the error they see the following error dialog\n### Example (validation error with a Fix-it action)\nThe following AL code illustrates how to set up field validation with a Fix-it action.\n```al\n...\nfield(17; \"Qty. to Invoice\"; Decimal)\n{\n    // maybe some field properties\n\n    trigger OnValidate()\n    var\n        CannotInvoiceErrorInfo: ErrorInfo;\n        CheckField: Boolean;\n    begin\n        // some calculations here\n\n        CheckField := // calculate if true or false\n\n        if (CheckField)\n        then begin\n            // setup the error info object\n            CannotInvoiceErrorInfo.Title := 'Qty. to Invoice isn''t valid';\n            CannotInvoiceErrorInfo.Message :=\n                StrSubstNo('You cannot invoice more than %1 units.', MaxQtyToInvoice());\n            CannotInvoiceErrorInfo.DetailedMessage('Add some text to help the person troubleshooting this error.');\n\n            CannotInvoiceErrorInfo.RecordId := Rec.RecordId;\n            CannotInvoiceErrorInfo.AddAction(\n                StrSubstNo('Set value to %1', MaxQtyToInvoice()),\n                Codeunit::FixitCodeunit,\n                FixitCodeunitMethodName\n            );\n\n            Error(CannotInvoiceErrorInfo);\n        end;\n        // maybe more validation logic here\n    end;\n}\n...\n```\nIf the user experience that the field can't be validated, they see the following dialog\n![Validation error with fix-it action]\n##  Error messages with Show-it actions\nShow-it actions are for when the error location is known. A shortcut can then be provided to show the related page to enable users to easily unblock themselves from the error. If all the following four statements are true for your error case, then consider adding a recommended Show-it action in your error message.\n1. Is the solution to the error known?\n2. Is the error correction location known and is it on a related table?\n3. Can you show the related table with one action?\n4. Does the user have permission to make the required correction?\n### Automatic Show-it actions from TestField\nNot all Show-it buttons require explicit ErrorInfo code. The single-parameter TestField(Field)<methods-auto/record/record-testfield-joker-method> method automatically adds a Show [Record] navigation button to the error dialog when validation fails. The platform resolves the target by finding a Card-type page whose SourceTable matches the record's table.\nThis implicit behavior has limitations compared to explicit ErrorInfo-based navigation:\n No field highlighting on the target page\n No custom button caption (always \"Show [Record Name]\")\n Always navigates to the default card page (can't specify an alternative page)\n No detailed message or title\nThe two-parameter TestField(Field, Value)<methods-auto/record/record-testfield-joker-joker-method> overload doesn't auto-generate navigation - it shows only a plain error with an OK button.\nIf you need more control over the Show-it behavior, use the ErrorInfo overloads of TestField or use `Error(ErrorInfo)` directly as shown in the examples in this section.\n### Guidance for button labels for Show-it actions\nTo achieve consistency in the user experience of Show-it actions, consider following these guidelines for button labels:\n Show-it actions are phrased: \"Show...\".\n   Such as: \"Show User Setup\", \"Show Items list\" or \"Show Item 70062\".\n Show-it action tooltips are often phrased: \"Opens page:..\".\n   Note: Avoid using \"Open\" for the button label, as it can be confused with opening the status of the document. Instead use \"Show\" and use the tooltip to write out \"Opens Page:...\".\n Captions are capitalized, such as: Item, Direct Posting and G/L Account.\n### Example (error dialog with a Show-it action)\nThe following AL code illustrates how to set up an error dialog with a Show-it action.\n```al\nprocedure ShowShipmentDialog()\nvar\n    ErrorNoLinesToCreate: ErrorInfo;\n    SomeCheckCondition: Boolean;\nbegin\n    // some business logic\n\n    SomeCheckCondition := // calculate if true or false\n\n    if (SomeCheckCondition)\n    begin\n        // maybe some business logic here\n\n        // setup the error info object\n        ErrorNoLinesToCreate.Title := 'There are no new warehouse shipment lines to create';\n        ErrorNoLinesToCreate.Message := 'This usually happens when warehouse shipment lines [...]';\n        ErrorNoLinesToCreate.DetailedMessage('Add some text to help the person troubleshooting this error.');\n\n        ErrorNoLinesToCreate.PageNo := Page::\"Warehouse Shipment List\";\n        ErrorNoLinesToCreate.AddNavigationAction('Show open lines');,\n\n        Error(ErrorNoLinesToCreate);\n\n        // maybe more business logic here\n    end;\n\n    // some more business logic here\n\n```\nIf the user experience the error they see the following error dialog\n### Example (validation error with one Show-it action)\nThe following AL code illustrates how to set up a validation error dialog with a Show-it action.\n```al\n...\nfield(59; \"Gen. Prod. Posting Group\"; Code[20])\n{\n    // maybe some field properties\n\n    trigger OnValidate()\n    var\n        CheckIfFieldIsEmpty: Boolean;\n        FieldEmptyErrorInfo: ErrorInfo;\n        ChangeNotAllowedErrorInfo: ErrorInfo;\n    begin\n        CheckIfFieldIsEmpty := // calculate if true or false\n\n        if (CheckIfFieldIsEmpty)\n        then begin\n            // setup the error info object\n            FieldEmptyErrorInfo.Message :=\n                StrSubstNo('Gen. Prod. Posting Group must have a value in item: %1. It can''t be zero or empty.', ItemNo);\n            FieldEmptyErrorInfo.DetailedMessage('Add some text to help the person troubleshooting this error.');\n\n            CannotInvoiceErrorInfo.RecordId := ItemRec.RecordId;\n            CannotInvoiceErrorInfo.AddNavigationAction(\n                StrSubstNo('Show Item %1', ItemNo)\n            );\n            ChangeNotAllowedErrorInfo.PageNo(Page::\"Item Card\");\n\n            Error(CannotInvoiceErrorInfo);\n        end;\n\n        // maybe more validation logic here\n    end;\n}\n...\n```\nIf the user experience that the field can't be validated, they see the following dialog\n![Validation error with show-it action]\n## Error messages with multiple actions - how to use them?\nError messages can have up to two recommended actions. In this section, we show some different examples of how to use multiple actions and why.\n### Example (error dialog with two actions)\nThe following AL code illustrates how to set up an error dialog with two actions.\n```al\nvar\n    ErrorDialogWithTwoActions: ErrorInfo;\n    DimensionCode: Code[20];\n    VendorCode: Code[20];\nbegin\n    // set values for DimensionCode, VendorCode variables\n\n    // setup the error info object\n    ErrorDialogWithTwoActions.Title := 'The line dimension value isn''t valid';\n    ErrorDialogWithTwoActions.Message := StrSubstNo('The dimension value must be blank for the dimension %1 for Vendor %2', DimensionCode, VendorCode);\n    ErrorDialogWithTwoActions.DetailedMessage('Add some text to help the person troubleshooting this error.');\n\n    ErrorDialogWithTwoActions.AddAction(\n        'Set value to blank',\n        Codeunit::FirstFixitCodeunit,\n        \"FirstFixitCodeunitMethodName\"\n    );\n    ErrorDialogWithTwoActions.AddAction(\n        'OK',\n        Codeunit::SecondFixitCodeunit,\n        \"SecondFixitCodeunitMethodName\"\n    );\n\n    Error(ErrorDialogWithTwoActions);\nend;\n```\nIn this error dialog case, the recommended Fix-it action sets the value to blank, meaning that it clears out the field value.\nNotice the error dialog has two actions. In error cases both buttons are styled equally as secondary buttons, to allow users to consider the most suitable way to get unblocked for their case.\nIf the user experience the error they see the following error dialog\n![Error dialog with multiple actions]\n### Example (validation error with two promoted actions)\nThe following AL code illustrates how to set up field validation with two actions.\n```al\nfield(4; \"Account No.\"; Code[20])\n{\n    // maybe some field properties\n\n    trigger OnValidate()\n    var\n        PendingApprovalErrorInfo: ErrorInfo;\n    begin\n        SomeCheckCondition := // calculate if true or false\n\n        if (SomeCheckCondition)\n        then begin\n            PendingApprovalErrorInfo.Message := 'You can''t modify a record pending approval. Add a comment or reject the approval to modify the record.';\n            PendingApprovalErrorInfo.DetailedMessage('Add some text to help the person troubleshooting this error.');\n\n            PendingApprovalErrorInfo.PageNo := Page::\"Comments\";\n            PendingApprovalErrorInfo.AddNavigationAction('Show comments');\n\n            PendingApprovalErrorInfo.AddAction(\n                'Reject approval'\n                Codeunit::SecondFixitCodeunit,\n                SecondFixitCodeunitMethodName\n            );\n\n            Error(PendingApprovalErrorInfo);\n        end;\n    end;\n}\n```\nHere the Show-it action shows the related Comments table, and the Fix-it action rejects the approval.\nUsers can also get unblocked by refreshing the page or copying the error details for sharing and troubleshooting.\nIf the user experience that the field can't be validated, they see the following dialog\n![Validation error with multiple actions]\n## Error messages with no actions (final resort)\nWhen there isn't any known solution to recommend, the error dialog has one primary OK button. Users can copy and share the full error details needed for troubleshooting and support.\nThe following AL code illustrates how to set up an error dialog with no actions (which is also the standard behavior of the Error method)\n```al\nvar\n    ErrorDialogNoActions: ErrorInfo;\nbegin\n    // setup the error info object\n    ErrorDialogNoActions.Title := 'The ''Starting Date'' isn''t valid';\n    ErrorDialogNoActions.Message := 'The ''Starting Date'' must be the first date of an accounting period. Try changing the date to first date of the month.';\n    ErrorDialogNoActions.DetailedMessage('Add some text to help the person troubleshooting this error.');\n\n    Error(ErrorDialogNoActions);\nend;\n```\nIf the user experience the error they see the following error dialog\n![Error dialog with no solution]\n## Related information\nFailure modeling and robust coding practices<devenv-robust-coding-practices>\nUser experience guidelines for errors<devenv-error-handling-guidelines>\nUnderstanding the error dialog<devenv-error-dialog>\nmethods-auto/dialog/dialog-error-errorinfo-method\ndevenv-al-error-handling"}