Symptoms, in the words you would use before you know the cause.
For the defect list — what is known-broken and where the fix goes — see known issues. This page is the index from what you are seeing to which page explains it.
| Symptom | Cause | Fix |
|---|---|---|
| A run sits on a step and nothing happens | npm run dev starts no worker, and input is the only type a request advances | npm run dev:all — installation |
npm run job:step exits immediately | requireSafeExecuteEnvOrExit() kills the worker when SAFE_EXECUTOR_PRIVATE_KEY or ETH_RPC_URL is unset | Set both, even to throwaway values — environment |
Every API call returns ECONNREFUSED, but the UI loads fine | MONGO_URL is set and nothing is listening on it | Start Mongo, or unset MONGO_URL to fall back to file storage — storage |
| No templates anywhere | Registry empty / wrong STORAGE_DRIVER, or reading a fresh store before any list/get | Confirm applications/main/src/templates/registry.ts; hit /templates once so storage gap-fills missing keys — manage templates |
tsc errors under .next/types/ | Stale generated types from a build on another branch | rm -rf .next |
| A change to the storage backend does nothing | The backend is bound once at module load | Restart — there is no runtime switch |
| Symptom | Cause | Fix |
|---|---|---|
| Login succeeds, then every screen is empty and every action is denied | Missing deployment policy, unverified email or app membership | Check target-scoped identity and application access |
| Login stalls after picking an organization | The silent org-scoped authorize returned consent_required | Enable Allow Skipping User Consent on the API |
| The org picker is empty | Missing or unscoped AUTH0_MGMT_CLIENT_ID / _SECRET | Grant read:organizations, read:users, read:roles |
| Login succeeds but actions are 403 | Missing target-app declared permissions | Review app role assignments — application access |
| Symptom | Cause | Fix |
|---|---|---|
| A step will not complete and nothing looks required | completeExpression, not mandatory. The 403 deliberately does not distinguish "not allowed" from "not complete" | Read the step's completeExpression — expressions |
| Editor changes vanish after saving | The step type is missing a case in flowToTemplate | add a step type |
A historical raw script definition will not save | Runtime source execution has been removed | Use the attested offline converter or author a closed template composition — template editor |
enabledExpression has no effect | Declared in the authoring model, never evaluated | known issue 3 |
| A repo template edit never reached the app | Process is using its snapshot, not the live template; or you edited storage only | Check process.template; for live list/start, confirm the key is in registry.ts |
templates:status looks all same | Expected — reads overlay/upsert shipped keys | Use status mainly for db-only rows — manage templates |
| A mandatory field is not being enforced | mandatory is skipped on hidden and read-only fields | Use completeExpression for conditional rules — field types |
| Symptom | Cause | Fix |
|---|---|---|
A run reads completed but clearly failed | failProcess() sets status = "completed" and populates error. There is no failure state | Check error — known issue 2 |
| A notification never arrived | The send failed; the run advances anyway by design | The step shows Not sent with the reason, the rail marks it, and the completion screen lists it — step types |
| A notification sent, but somebody was not pinged | Mentioned users who are not in the channel are dropped by Slack | The step shows Sent, but not to everyone and names them. Invite them to the channel |
Slack says no channel named … | The bot is not in the channel, or the channel does not exist | The bot must be invited; private channels must be joined to be listable |
| A step retries endlessly and logs every second | An unguarded throw — condition, automatic, wait, request, or a notify transport error | known issue 1 |
| An expression fails on a step that has not run yet | Context is populated as the run advances; earlier keys may be absent | Guard it: input.foo && input.foo.length > 0 |
| A progress bar sits at 90%, or moves backwards | Progress counts array position, and array order is meaningless | known issue 9 |
"Awaiting My Sign-off" always reads 0 | Hardcoded, never computed | known issue 7 |
The dashboard and /processes disagree about the same run | They derive failure differently | known issue 8 |
| Fixing a template did not fix a run already in flight | The run follows the snapshot taken at start | Expected — templates |
| Symptom | Cause | Fix |
|---|---|---|
| The server renders one brand and the browser renders another | NEXT_PUBLIC_* is only inlined on static property access; a dynamic lookup is empty client-side | Read process.env.NEXT_PUBLIC_FRONTEND_ID directly — whitelabel |
| The app throws at startup after a deploy | NEXT_PUBLIC_FRONTEND_ID names an unregistered profile | Deliberate: a typo fails the deploy instead of shipping the wrong brand |
| A route is hidden from the sidebar but users still reach it | A skin is presentation, not an access boundary | Gate it with a permission — permissions |
| Symptom | Cause | Fix |
|---|---|---|
| The worker dies right after deploy | Missing SAFE_EXECUTOR_PRIVATE_KEY or ETH_RPC_URL | deployment |
| Nothing advances, but the app looks healthy | Zero workers running, or one that crashed. There is no heartbeat and no alerting | Supervise the worker process |
| The same step executes twice | Two workers on one database. The overlap guard is in-process only | Exactly one worker per database — deployment |
| A new step type can be authored but never executes | The worker is on an older build than the web service | Rebuild/deploy the compatible Platform runtime and compiled registration/capability configuration together |
| Links in notifications point at the wrong deploy | APP_BASE_URL is not that service's own origin | Each web deploy needs its own |
Use a focused check while iterating, then the complete gate before handoff:
npm run typecheck # source, fixtures and test configuration npm test # Node unit/service tests npm run check:docs # documentation links, counts and stale claims npm run verify # complete local architecture/regression gate
For configured tests and their remaining coverage/enforcement limits, see known issue 4. For anything touching a step type, the fastest real check is to add it to a repository template, restart the app (startup publishes the changed digest), and confirm the step renders in the template viewer and the runner.