Epicor BPM Runtime Error: Where to Look and How to Fix It
epicor bpm runtime error
Also searched as
- epicor bpm object reference not set to an instance of an object
- epicor bpm compile error directive
- epicor bpm directive not firing
- epicor bpm error in server log
Short answer
A BPM runtime error is an exception thrown while a directive runs, so the user's save or action fails. Find the directive name and line in the client trace or server log, then check the usual causes: a null reference in custom code, a directive that no longer compiles after a change, conflicting directive order, or a lock or validation error from a nested update.
Applies to: Epicor Kinetic and 10.x, Method and Data directives, on-prem and cloud (cloud log access differs).
How to diagnose a BPM runtime error
- 1Reproduce the action with the client trace on (Options > Tracing Options) and note the exact error text the user sees.
- 2Copy the Details of the error dialog. It usually names the business object, method and sometimes the directive.
- 3On-prem, open the server log location configured in the Epicor Administration Console for the app server, and the Windows Event Viewer on the app server, and search for the timestamp.
- 4Open Method Directive Maintenance, find the directive, and check it is Enabled and which directive group it belongs to.
- 5Disable the suspect directive in the pilot company and retry. If the error disappears, the directive is confirmed as the cause.
- 6Fix the code or the logic, validate, save and deploy, then retest with the same data.
- 7Re-enable in live only after a pilot company run.
The usual causes
Null reference is the number one cause. Code such as Db.Part.Where(...).FirstOrDefault().PartDescription throws when no row matches, or when a ttTable has no row for that RowMod. Always test for null before use, and check the table has rows before calling First.
The second is a directive that stopped compiling. A schema change, an upgrade, a renamed UD field or a removed widget can leave a saved directive that no longer builds. After an upgrade, open key directives and validate them.
Third is directive order and conflicts. Several directives on the same method run in sequence, and one can change data that the next one assumes. Review the directive groups and order numbers when two rules touch the same field.
Where the error is recorded
The user-facing dialog shows a short message and a Details view with the stack. The server side keeps more: the application server log set up in the Epicor Administration Console, and the Windows event log. The exact paths depend on how your server was installed, so ask your Epicor administrator for the log location rather than guessing.
The client trace is the quickest tool when you cannot reach the server: it records the calls and responses so you can see which method failed and the returned error. Turn it off afterward because it adds overhead.
Defensive patterns that prevent repeats
Wrap lookups in null checks, write explicit exception messages naming the part, order or line, and keep each directive small. A short message such as Part X is inactive on line 3 saves hours compared with a stack trace.
For multi-step logic use an Epicor Function and a single call widget, so the logic can be tested alone and reused. Keep custom code out of high-traffic methods unless it is guarded by a condition.
var cust = Db.Customer.Where(c => c.Company == Session.CompanyID && c.CustNum == ttOrderHed[0].CustNum).FirstOrDefault();
if (cust == null)
{
throw new Ice.Common.BusinessObjectException("Customer not found for order " + ttOrderHed[0].OrderNum);
}Try it here, free
Epicor BPM Directive Types Reference
Lookup table of Epicor BPM directive types, when each runs, whether it can stop a save, and typical use.
Common pitfalls
- !Fixing the symptom in the live company without a pilot test. A new bug can stop all order entry.
- !Assuming the error comes from the screen you used. It may come from a directive on a method the screen calls indirectly.
- !Leaving old test directives enabled, so they fire in the wrong company.
- !Reading only the first line of the dialog. The Details usually have the actual line and cause.
How an ERP-grounded AI assistant handles this
An assistant that can read the exported error text, the directive definitions and your schema can narrow the likely cause, for example pointing at the FirstOrDefault that has no null test. It suggests; your developer changes and tests. Running the model on-prem keeps stack traces and customisations inside your network.
Frequently asked questions
What does Object reference not set to an instance of an object mean in a BPM?
Your code used a value that was null, usually a database lookup that found nothing or a temp table with no matching row. Add a null check and a clear error message before using the object.
Why does my BPM stop working after an upgrade?
Schema or API changes can break compilation of custom code or widgets. Open the directive, validate it, correct any renamed fields, save and deploy again. Review upgrade notes for removed or changed members.
Can I see which directive threw the error?
Often yes from the Details of the error dialog and the server log. If not, disable directives one at a time in a pilot company, starting with the ones on that business object and method.
How do I stop one bad directive blocking everyone?
Disable it in Method Directive Maintenance, then deploy. Fix it in a pilot company with the same data before enabling again in the live company.
Related
Fixing Epicor BusinessObjectException: BPM Directive Errors
A BusinessObjectException that says "A Business Process Management (BPM) directive has raised the following error" means a directive on that business object stopped the transaction, either deliberately via a Raise Exception widget or accidentally via an unhandled .NET error in Custom Code. Expand the InnerException on the error dialog to see the real message and the directive name, then open BPM Designer for that object and method to find the widget that fired.
How-toEpicor BPM Custom Code Examples: Set, Query, Validate, Call and Refresh
A BPM Custom Code block is a C# snippet that runs inside a Method or Data directive and can read the incoming temp tables (ttOrderHed, ttOrderDtl and so on), query the database through Db, and call business objects. Below are tested-pattern examples for setting a field, looking up a record, validating and raising an error, and calling a service, plus how to make the client see data you changed.
AdvancedEpicor BPM TxScope: Standard vs In-Transaction Directives and When Functions Need a Transaction
A transaction scope groups database writes so they commit or roll back together. In Epicor BPM, a Standard directive runs outside the business object's database transaction, while an In-Transaction directive runs inside it, so an exception rolls back the whole save. In custom code you open your own scope with IceContext.CreateDefaultTransactionScope and call Complete.
How-toHow to Create a BPM Method Directive in Epicor Kinetic
In Epicor Kinetic, open Business Process Management > Method Directive Maintenance (the BPM Workbench), pick the business object and method, choose Pre-Processing, Base Processing or Post-Processing, then add a condition and actions such as Show Message or Set Field. Enable it and test in a pilot company before production.
How-toFixing a Slow Epicor BAQ (Business Activity Query)
A slow BAQ in Epicor is usually caused by unindexed join columns, a subquery or calculated field forcing a table scan, or the BAQ pulling far more rows than the dashboard actually displays before filtering client-side. Fix it by reading the SQL Server execution plan Epicor generates, moving filters into the BAQ criteria instead of the dashboard filter panel, and replacing subqueries with joins where possible.
How-toEpicor MRP Runs but Generates No Suggestions
When Epicor's MRP process completes without a job or purchase suggestion for a part you expect one for, the cause is almost always the part's own configuration (Part Class Type, Make Direct, Non-MRP flag, planning Time Fence) or the demand not being linked in a way MRP recognizes, not a defect in the MRP engine. Work through the part's Planning tab, its safety stock and lead time setup, and the demand source (sales order line status, job material requirement) before assuming the run itself failed.
AI for ERPAI for Epicor Kinetic, Beyond What Prism Covers
Add AI to Epicor Kinetic beyond Prism: private LLM over BAQs, BPM data, and REST v2, on-prem or private cloud, with honest guidance on when Prism already covers you.
Stuck on Epicor Kinetic?
Talk to engineers who work inside Epicor Kinetic every week, and who build private AI that answers these questions from your own ERP data.
Keep exploring
Free tools
- Epicor BPM Directive Types ReferenceLookup table of Epicor BPM directive types, when each runs, whether it can stop a save, and typical use.
- Epicor BPM Directive Design TemplateA fill-in design document for BPM method and data directives covering trigger, conditions, actions, testing and rollback.
- Epicor BPM Directive Overhead CalculatorSee how many milliseconds and server hours your BPM directives add per transaction and per day.
ERP fixes and how-tos
- How to Create a BPM Method Directive in Epicor KineticHow to build a Method Directive in Epicor Kinetic: choose the business object method, pre or post processing, add conditions and actions, test, and deploy safely.
- Epicor BPM Data Directives and the Workflow Designer: When to Use Each, With an ExampleEpicor BPM data directives versus method directives, how the BPM Workflow Designer canvas works, and a worked example that blocks a save when data is missing.
- Fixing Epicor BusinessObjectException: BPM Directive ErrorsA BusinessObjectException wrapping a BPM directive error in Epicor means a Pre-Processing, Post-Processing or Data Directive stopped the transaction. Here is how to trace and fix it.
AI on your ERP
- AI for Epicor Kinetic, Beyond What Prism CoversAdd AI to Epicor Kinetic beyond Prism: private LLM over BAQs, BPM data, and REST v2, on-prem or private cloud, with honest guidance on when Prism already covers you.
- Private AI for Epicor Kinetic Cloud, Outside the Multi-Tenant BoundaryRun a private LLM on Epicor Kinetic private cloud or Kinetic Cloud data via BAQs, REST v2 and Data Fabric, keeping sensitive manufacturing data off shared AI.
Integrations
- How to add WhatsApp to Epicor KineticHow to connect WhatsApp Business to Epicor Kinetic: REST and BPM triggers, template messages, opt-in rules and two-way replies that post back to the ERP.
- How to add Microsoft Teams to Epicor KineticSend Epicor Kinetic approvals and alerts to Microsoft Teams with adaptive cards, Entra ID sign-in, BPM triggers and REST write-back that respects ERP roles.