Troubleshooting

Tap a symptom to expand its checks. Use the browser's Find in Page (Ctrl/Cmd + F) to search across all entries, including closed ones.

• Runner not connecting

  Verify the hub URL (including protocol and port). Test network connectivity with curl to /api/health. Check machine credentials match the registered values. Review runner logs for specific errors (401, ECONNREFUSED, ETIMEDOUT).

• Workflow not executing

  Check for available ONLINE runners. Ensure the workflow has a published version. Verify the license status is ACTIVE or GRACE_PERIOD. Check Redis connectivity for queue processing.

• Trigger not firing

  Verify the trigger is enabled. For schedules: validate the cron expression and check the hub's system clock. For webhooks: test the URL with curl and check firewall rules.

• Database connection issues

  Verify PostgreSQL is running (pg_isready). Check the DATABASE_URL in .env. Test direct connectivity with psql. Check firewall rules between hub and database servers. Run Prisma migrations manually if the schema is missing.

• Execution stuck in pending

  The stale execution check runs every 60 seconds. Ensure runners are ONLINE. Check Redis connectivity. QUEUED executions are marked FAILED after 10 minutes. ASSIGNED executions with offline runners are re-queued after 5 minutes.

• Service fails to start

  Check service-stderr.log for errors. Common causes: port in use, missing Node.js binary, missing TLS certificates, invalid configuration. Test manually by running launcher.js directly.