NirmaanOne Help
How-toReviewed 2026-09-29

Investigate a failed automation

When a reminder, task or automatic run didn't happen, check that the workflow engine is working, find the run that failed and read its error, fix the cause, then retry the run or requeue the event.

Investigate a failed automation

Someone says a payment reminder never went out, an overdue demand wasn't escalated, or the monthly demand run didn't appear. Work through the automation's trail: is the engine working, did the rule run at all, which step failed and why. Once the cause is fixed, the failed run can pick up where it stopped.

Before you start

  • The Health tab and Requeue need the Edit permission on Workflow Rules; the Runs and Outbox tabs need the View permission on Workflow Runs; Retry needs the Edit permission on Workflow Runs. In the default roles only the Administrator holds all of them. Other roles see runs (most have the View permission on Workflow Runs) but can't retry.
  • Know roughly which record and which day the automation concerned: it narrows the lists quickly.

Steps

  1. Open the account menu > Settings > Workflows > Health (Health), or click Open Health in the yellow warning "<reason>: rules are saved and changes are kept, but runs stay Pending until it is fixed." Read the three cards: healthy is Automation On, Queue Connected and Processing Idle or Processing, with Oldest pending "none" or a few seconds. Off, Not set up, Not answering or Backlog is stuck mean nothing is being processed: pass the card's detail to whoever looks after your server. Nothing is lost meanwhile; runs wait as Pending.
  2. In the Runs card, click the count next to Errored. The Runs tab opens filtered to Errored, newest first. Narrow it with the Any rule and Any entity filters and the two date boxes if needed; the first line of each error shows under Status.
  3. Click the eye icon on the run that concerns you. The panel "Run <id>" shows the Rule, the Record, the Trigger event, the error in a red box and, under Actions, each step with its status and error text. Common errors:
    • "permission_revoked: the acting user no longer holds …": the person the rule acts as (who last saved or switched it, or who pressed a manual button) lost a permission or was deactivated;
    • "no_recipients: No valid email address after rendering the recipients": the record's contact has no email address;
    • "no_assignee: Role '<name>' has no active members": the role a task or assignment goes to is empty;
    • "reason_required: The cancellation reason rendered empty": a reason text came out blank;
    • "webhook_failed: Webhook answered <status>: …": the other system refused the call;
    • "The entity no longer exists": the record was deleted before the run.
  4. Click the rule's name in the panel to open it (Rule), then Test: pick the same Record and click Run dry run. The dialog shows whether the rule still matches the record and a verdict per step, such as Would run, Skipped by conditions or Blocked: missing permissions with "Missing: …".
  5. Fix what the error names. For a revoked permission, give the permission back under Roles & Permissions, or have someone who holds it switch the rule off and on (on a custom rule, flip its Active switch on Rules; on a system rule, Switch off then Switch on), which makes them the owner. For a missing email, add it to the contact under Contacts. For an empty role, give it an active member under Users. For a wording or document problem, correct the message template or publish the document template.
  6. Back on Runs, open the run again and click Retry. You see "Retry queued; the run resumes at the first action that did not finish." Steps that already succeeded are not repeated; the panel follows the run ("following…") until it reads Success.
  7. If the Outbox card on Health counts Failed events, open the Outbox tab, set Status to Failed and click the eye icon on an event. The panel shows Last error, the Record, Changed columns and "No runs yet." (or the runs it produced).
  8. Click Requeue. You see "Event requeued; it is picked up within a few seconds." The event goes back to Pending and, once processed, lists the runs it produced.

What happens next

  • No run at all usually means the rule didn't match. A rule only produces a run when its trigger fired and its conditions held; a change that no active rule listens to writes nothing to the outbox. Check that the rule is Active, in scope for the record's project and (for On Update rules) watching the column that changed, and use Test on the record.
  • Rules don't react to other rules. A task, assignment or update made by a rule never triggers another rule, so "Task assigned" isn't sent for a task a rule created. Only a custom event chains rules (Chain two rules with a custom event).
  • Reminders fire once a day. Overdue and instalment-due events are raised by a daily check at 08:00 India time, not the moment a demand becomes overdue.
  • An email step can succeed without sending. When your server has no mail set up, Send email and Generate document steps end Success with "MAIL_SERVER is not configured; the message was logged" in their Result, and nothing leaves.
  • The outbox is a recent log. Processed events are cleared after 30 days; the runs themselves stay.

If something goes wrong

  • Runs stay Pending, the panel reads "Waiting to be picked up.", or Health shows Off, Not set up, Not answering or Backlog is stuck: automation isn't running. See Runs stay Pending (trouble.workflows.runs-stay-pending).
  • "permission_revoked: the acting user no longer holds …", or "You do not have permission to do that." when switching the rule: see Run errored: permission revoked (trouble.workflows.run-errored-permission-revoked).
  • "no_recipients: …" or an email that was only logged: see Email not sent (trouble.workflows.email-not-sent).
  • "Only errored runs can be retried." or "This rule is inactive." on Retry: the run has moved on, or the rule is switched off (switch it on first, as someone who holds its permissions). See Run errored: permission revoked (trouble.workflows.run-errored-permission-revoked). "Only failed events can be requeued." on Requeue: the event has moved on; refresh the list. See Runs stay Pending (trouble.workflows.runs-stay-pending).
  • "no_assignee: Role '<name>' has no active members", "reason_required: …", "webhook_failed: …", "Template <CODE> is not published" or "<n> action(s) failed and were skipped: …": one step failed for a reason of its own. See Action failed (trouble.workflows.action-failed).
  • A run reads Blocked with "Blocked: <CODE> from rule "<name>" would run at trace depth <n> (maximum <m>)": a chain of rules went too deep; it can't be retried. See Action failed (trouble.workflows.action-failed).
  • The Health tab isn't shown, or a tab reads "You do not have permission to view workflow runs. Ask your administrator.": see No access (trouble.admin.no-access).

Related

  • HealthScreen

    Whether the automation engine can process what the rules produce: the engine flag, its message queue, its worker, the outbox and run counts, and the scheduler's heartbeat.

  • RunsScreen

    Every time a rule ran: what started it, which record it worked on, how each action went, and the panel from which an errored run is retried.

  • OutboxScreen

    The events recorded when records change, on their way to the rules that listen to them, with the runs each event produced and the panel from which a failed event is requeued.

  • RuleScreen

    One automation rule's page: read or change its basics, trigger, conditions and actions, test it against a record, clone or delete it, and switch a system rule on or off.

  • RulesScreen

    Every automation rule in your organization, system and custom, with filters, the switch that turns each rule on or off, and shortcuts to edit, test, clone, see the run history of or delete a rule.

  • WorkflowsScreen

    The Workflows area of Settings, where you manage automation rules, event types and message templates, and check the runs, the outbox and the engine's health.

  • Roles & PermissionsScreen

    The list of your organization's roles: open one, create or clone a role, deactivate or reactivate it, and delete custom roles nobody holds.

  • UsersScreen

    The people in your organization: invite new users, change their role, deactivate or reactivate them, reset a lost two-factor authentication, and resend or revoke pending invitations.

  • ContactsScreen

    The master list of every person your organization deals with, with a panel to add, edit, deactivate or delete a contact and see who changed the record.

  • Build and switch on a custom ruleHow-to

    Build your own automation rule on the rule editor (what it watches, what starts it, which records qualify and what it does), save it switched off, try it on a real record with a dry run, then switch it on and check its runs.

  • Chain two rules with a custom eventHow-to

    Make one rule start another: define a custom event type, let the second rule listen to it with the On Event trigger, and have the first rule raise it when it finishes.

  • Workflow runs and the outboxConcept

    How a change becomes automation: the outbox event written with the change, the pick-up that hands it to the engine, one run per listening rule with a recorded result per action, the statuses each passes through, and how Errored runs are retried and Failed events requeued.

  • Workflow rules, conditions, actions and the rule ownerConcept

    What a workflow rule is made of (one kind of record, one trigger, conditions, ordered actions, an optional chained event), how conditions and action settings are evaluated, how versions, tests and clones work, and why every rule has an owner whose permissions its runs use.

  • Workflow runs stay Pending: automation is off, its queue is down or processing has stoppedTroubleshooting

    Rules keep saving and events keep being recorded, but nothing runs while automation is switched off on the server, the queue that carries changes to it is missing or down, or processing has stopped; the Health tab shows which, the NirmaanOne team fixes it, and the waiting work is then processed.

  • Run errored or blocked with "permission_revoked": the rule's owner no longer holds a permission its actions needTroubleshooting

    A rule's automatic runs act as the person who last saved or switched the rule, and manual runs as the person who pressed the button; each action is checked against that person's permissions when it runs, so a role change or a deactivated user makes the run fail until the permission is restored or someone who holds it takes the rule over.

  • Email action or document email did not go out: no valid recipient, or the message is incompleteTroubleshooting

    A Send email action fails when its To line renders no valid address (usually because the contact has no email), a rule with Send email cannot be saved without a message template or a subject and body, a document email needs at least one valid address and is refused for a void document, and an Email message template needs a subject.

  • A run's action errored: webhook refused, empty role, empty reason, unpublished template or the chain ran too deepTroubleshooting

    A workflow run stops as Errored when one of its actions fails: the webhook address is internal or the other system refused the call, the role to assign to has no active members, a cancellation or lost reason came out blank, or the document template is not published; a run is Blocked when a chain of rules emitting events runs deeper than the engine allows.

  • "No access" or "You do not have permission": your role lacks a permissionTroubleshooting

    Every screen, button and picker is gated by a permission on a module; your role decides which you hold, so a missing one shows as a No access card, a refused action, a greyed-out button with a hover reason, or a picker that explains which permission it needs.