workflow-debugging
starsforks
How to install workflow-debugging?
adobe/skills/workflow-debugging
$npx -y skills add adobe/skills --skill workflow-debuggingDebug AEM Workflow issues on AEM 6.5 LTS and AMS including stuck workflows, failed steps, missing Inbox tasks, launcher failures, stale instances, thread pool exhaustion, queue backlogs, purge failures, and permissions errors. Use when the user reports workflow problems on AEM 6.
SKILL.md
| 1 | # AEM Workflow Debugging — 6.5 LTS / AMS |
| 2 | |
| 3 | Production-grade debugging for AEM Granite Workflow engine, launcher, Inbox, Sling Jobs, thread pools, and purge on **AEM 6.5 LTS** and **Adobe Managed Services (AMS)**. |
| 4 | |
| 5 | ## Variant Scope |
| 6 | |
| 7 | - This skill is **6.5-lts-only** (includes AMS). |
| 8 | - Full JMX access via Felix Console or JMX client. |
| 9 | - Config changes via Felix Console or OSGi config in repository. |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## When to use this skill |
| 14 | |
| 15 | - Workflow stuck, not progressing, failed, not starting, task not in Inbox, purge/repository bloat, permissions, queue backlog, thread pool exhaustion, auto-advancement not working. |
| 16 | - User provides thread dumps, configuration status ZIPs, Sling Job console output, or error.log excerpts. |
| 17 | - Environment: AEM 6.5 LTS / AMS (JMX available). |
| 18 | |
| 19 | --- |
| 20 | |
| 21 | ## Step 1: Map symptom to first action |
| 22 | |
| 23 | | Symptom | symptom_id | First action | |
| 24 | |---------|------------|--------------| |
| 25 | | Workflow stuck (not advancing) | workflow_stuck_not_progressing | Open instance; note current step type. No work item → stale. | |
| 26 | | Task not in Inbox | task_not_in_inbox | Confirm Participant step; assignee = logged-in user; Inbox filters. | |
| 27 | | Workflow not starting (launcher) | workflow_not_starting_launcher | Launcher enabled; path/event match payload. | |
| 28 | | Workflow fails or shows error | workflow_fails_or_shows_error | Instance history; error.log for instance ID; payload and process. | |
| 29 | | Step failed, retries exhausted | step_failed_retries_exhausted | Logs → process.label → JMX `retryFailedWorkItems` or Inbox retry. | |
| 30 | | Stale (no current work item) | stale_workflow_no_work_item | JMX `countStaleWorkflows` → `restartStaleWorkflows(dryRun=true)`. | |
| 31 | | Repository bloat / too many instances | repository_bloat_too_many_instances | JMX `purgeCompleted(dryRun=true)` or Purge Scheduler. | |
| 32 | | User cannot see or complete item | user_cannot_see_or_complete_item | Assignee/initiator/superuser; enforce flags. | |
| 33 | | Cannot delete model | cannot_delete_model | JMX `countRunningWorkflows` → terminate → delete. | |
| 34 | | Slow throughput / queue backlog | slow_throughput_queue_backlog | JMX `returnSystemJobInfo`; `queue.maxparallel` on Granite Workflow Queue; Sling thread pool. | |
| 35 | | Auto-advancement not working | workflow_auto_advance_failure | Check `default` thread pool saturation; Sling Scheduler; timeout jobs. | |
| 36 | | New workflow not working | workflow_setup_validation | Model sync, launcher, process registration, permissions. | |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## Step 2: Decision tree (workflow stuck) |
| 41 | |
| 42 | 1. **No current work item?** → Stale. JMX: `countStaleWorkflows` → `restartStaleWorkflows(dryRun=true)`. |
| 43 | 2. **Participant step** → Assignee exists? Inbox visible? Payload accessible? Dynamic participant resolver returning correct user? |
| 44 | 3. **Process step** → Search error.log for instance ID. Check: `process.label` registered, payload path exists, bundle active, no exception in `execute()`. |
| 45 | 4. **OR/AND Split** → Condition evaluates correctly? Routes exist? No dead-end branches? Model synced? |
| 46 | |
| 47 | --- |
| 48 | |
| 49 | ## Step 3: Thread dump & thread pool analysis |
| 50 | |
| 51 | Thread dumps on 6.5 / AMS are obtained via **jstack** or by requesting from AMS support. Configuration status ZIPs from **Felix Console → Status → Configuration Status**. |
| 52 | |
| 53 | ### 3a. Sling `default` thread pool (critical path) |
| 54 | |
| 55 | The Sling Scheduler `ApacheSlingdefault` uses `ThreadPool: default`. This pool runs: |
| 56 | - Oak observation events |
| 57 | - All Quartz-scheduled jobs — including the workflow timeout-detection scheduler that emits `com/adobe/granite/workflow/timeout/job` events to the Sling Job system (the job itself then runs on the Granite Workflow Queue, see Step 3c) |
| 58 | |
| 59 | **Check the Sling Thread Pools status page (`/system/console/status-slingthreadpools`):** |
| 60 | |
| 61 | | Field | Healthy | Problem | |
| 62 | |-------|---------|---------| |
| 63 | | active count | < max pool size | **= max pool size** (saturated) | |
| 64 | | block policy | RUN | **ABORT** (rejects tasks when full) | |
| 65 | | max pool size | sized for workload | OOTB on AEM 6.5 LTS is **5/5** (Apache Sling default). Bump to 20+ in OSGi config for environments with many custom periodic schedulers, otherwise schedulers can starve. | |
| 66 | |
| 67 | **If active count = max pool size AND block policy = ABORT:** |
| 68 | - New scheduled tasks (including workflow timeout/auto-advance jobs) are **silently rejected** |
| 69 | - This is the #1 cause of auto-advancement failure |
| 70 | |
| 71 | **Check the Threads status page (`/system/console/status-Threads`) or the jstack thread dump (`/system/console/status-jstack-threaddump`):** |
| 72 | - Search for `sling-default-` threa |
People who liked this also viewed
6 picksType
- azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026
- systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026
- safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026
- explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026
- minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026
- insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 2026
