Troubleshooting Workflows

Workflow fails immediately after starting

Symptom: A workflow transitions from Submitted or Approved directly to Failed within seconds, before any meaningful action has been attempted. The workflow detail page shows an error message.

1. 1

   Open the workflow detail and read the failure reason

   Click on the failed workflow to open its detail view. Every workflow failure includes a reason field. This will tell you whether the failure is a validation error, a connector problem, a permissions error, or a configuration issue.

2. 2

   Check whether the required connector is connected

   If the failure reason mentions a connector (e.g., 'Entra ID connector unavailable'), go to Integrations and verify the connector's status. A disconnected connector will cause workflows that depend on it to fail immediately at the execution stage.

3. 3

   Verify that the workflow has valid input data

   Some failures happen because the workflow was submitted with incomplete or invalid fields. For example, an onboarding workflow may fail if the target user's email domain is not allowed or a required field was empty. Review the submitted request data in the workflow detail.

4. 4

   Check RBAC — confirm the submitter has the required role

   Workflows that require elevated actions may fail if the submitter's role does not permit the action. Verify the user who submitted the workflow has the role required by the workflow definition.

5. 5

   Retry the workflow after resolving the root cause

   After fixing the underlying problem (reconnecting the connector, correcting input data, or updating permissions), use the Retry button on the failed workflow. Do not create a duplicate workflow unless the original is fully cancelled.

Workflow stuck in running state

Symptom: A workflow shows a status of Running but has not progressed or updated for more than 15 minutes. No error is shown, but no completion event appears.

1. 1

   Check the last progress timestamp

   In the workflow detail view, look for a 'Last updated' or step-by-step progress log. If the last step timestamp is recent (within the last 5 minutes), the workflow is still progressing. Give it more time before intervening.

2. 2

   Check the health of the connector the workflow depends on

   Go to Integrations and run Test Connection on the connector the workflow uses. If the connector is unhealthy, the workflow step that calls it may be waiting for a timeout before failing. Reconnect the connector.

3. 3

   Check the job queue for backlog

   Go to Settings > Scheduled Jobs or the Job Queue page and check whether there is a large backlog of queued jobs. A queue backlog can delay workflow steps that hand off to background workers.

4. 4

   Wait for the workflow's built-in timeout

   Nuxari workflows have a built-in execution timeout (typically 30–60 minutes depending on the workflow type). If the workflow times out, it will automatically transition to Failed with a timeout error. You can then review and retry.

5. 5

   Cancel and restart only if the workflow has not executed any steps

   If the workflow is confirmed to be at step 1 (no actions have been taken in the target system), it is safe to cancel and restart. If actions have already been taken (e.g., a user was created), contact Nuxari support before cancelling to avoid orphaned accounts or access.

Onboarding workflow not completing

Symptom: An onboarding workflow was approved and started but does not reach Completed status. It may be stuck in Running, or it failed at a specific provisioning step.

1. 1

   Check which provisioning step failed

   In the onboarding workflow detail, expand the execution steps. Each step (create user, assign groups, assign licenses, send welcome email) has its own status. Identify the first step that shows as Failed or Pending.

2. 2

   For user creation failures: check for duplicate email

   If the 'Create User' step fails, the most common cause is that a user with that email address already exists in the target directory (Entra ID, Okta, Google). Check the target directory for an existing account with the same email and either remove the duplicate or use a different email.

3. 3

   For group assignment failures: verify the group exists

   If a group assignment step fails, confirm that the target group exists in the identity provider and that the connector has permission to add members. A group that was renamed or deleted since the workflow template was configured will cause this step to fail.

4. 4

   For license assignment failures: verify available license seats

   If a license assignment step fails with 'No available licenses', your organization has run out of seats for that license type. Purchase additional seats or reclaim unused licenses before retrying.

5. 5

   Retry the failed step after resolving the root cause

   After fixing the underlying problem, return to the workflow and use the Retry option. The workflow will resume from the failed step, not from the beginning.

Offboarding workflow not revoking access

Symptom: An offboarding workflow completed successfully but the departed user still has access in one or more connected systems. Or the workflow failed midway through the revocation steps.

1. 1

   Check the workflow step log for which systems were revoked

   In the offboarding workflow detail, each connected system has its own revocation step. Review each step's status to identify exactly which systems completed revocation and which did not.

2. 2

   Manually revoke access in any system where the step failed

   Go directly to the target system's admin console (Entra ID, Okta, Google Workspace, etc.) and manually revoke or disable the departed user's account. Do not wait for the Nuxari workflow to be retried before taking this action.

3. 3

   Reconnect the failing connector and retry the workflow

   After manual revocation, fix the underlying connector failure and use the Retry option on the workflow. The retry will attempt the failed steps again, and when they complete, the audit log will reflect the completion.

4. 4

   Generate an evidence record of manual revocation

   If access was revoked manually rather than through Nuxari, create an audit note or attach supporting evidence (e.g., a screenshot of the account being disabled) to the workflow record for compliance purposes.

5. 5

   Review which systems are included in the offboarding template

   If certain systems are consistently not included in offboarding, review the offboarding workflow template configuration. Ensure all required systems are present as steps in the template. Missing connectors will never be covered by the workflow.

Scheduled job not running

Symptom: A scheduled governance job (control pack evaluation, report generation, access review) did not run at its configured time, or shows as Overdue in the Scheduled Jobs page.

1. 1

   Confirm the job is enabled

   In Settings > Scheduled Jobs, open the job and confirm its status is Enabled, not Paused or Disabled. An admin may have paused the job during maintenance and forgotten to re-enable it.

2. 2

   Check the job's configured schedule

   Verify the cron schedule or recurrence setting is correct. A common mistake is setting a job to run once per month but using the wrong day of the month, causing it to appear to skip months.

3. 3

   Verify the job's assigned connector is healthy

   Scheduled jobs that depend on a connector will not run if the connector is disconnected. The job may skip silently rather than failing visibly. Check the connector health and reconnect it if needed.

4. 4

   Check the job queue for backlog

   If many jobs were queued at the same time (e.g., after a system restart), there may be a queue backlog. The job may be queued and waiting for a worker to pick it up. Check the queue depth and wait for backlog to clear.

5. 5

   Trigger a manual run to test the job

   Use the Run Now button to trigger the job manually. If it runs successfully on demand but not on schedule, the problem is with the schedule configuration. If it also fails on demand, the problem is with the job itself or its dependencies.

Workflow approval stuck

Symptom: A workflow is in Pending Approval state for an extended period. No approver has acted on it, and no escalation notification has been sent.

1. 1

   Identify who the approval is assigned to

   In the workflow detail, the Approval step shows which user or role the approval request was sent to. Confirm that person is aware of the pending request — they should have received an email notification.

2. 2

   Check whether the approver has a Nuxari account

   If the approval was routed to a user who does not have a Nuxari account or whose account has been deactivated, they will not receive the notification and cannot approve. Verify the approver's account status in Settings > User Management.

3. 3

   Reassign the approval to a different approver

   A workspace admin can reassign a pending approval to a different user with the Approver role. In the workflow detail, click Reassign Approval and select an active approver.

4. 4

   Check notification delivery

   Ask the intended approver whether they received the approval email. If not, check the workspace notification settings and the user's spam folder. Add nuxari.io to your organization's email allowlist if delivery is inconsistent.

5. 5

   Set an approval timeout on the workflow template

   If approvals frequently sit unacted upon, configure an approval timeout in the workflow template settings. After the timeout period, the workflow can auto-escalate to a fallback approver or auto-reject, preventing indefinite blocking.