Opscraft
Jenkins · Lesson 9 of 11 · 3 min read

Troubleshooting Jenkins

Symptom Likely cause Action
Builds stuck "Waiting for next available executor" Label mismatch, agents offline/busy, K8s pods Pending Check label expression, node status, kubectl get pods -n <agents-ns> and events, quotas
Agent goes offline repeatedly Agent JVM OOM, disk full, network/WebSocket timeouts, idle timeouts on LB Agent logs, disk, increase heap, LB idle timeout, ping thread settings
Controller disk filling weekly No build retention, big artifacts, workspaces on controller buildDiscarder, external artifact storage, 0 executors, cleanWs()
UI slow / hangs Heap pressure, GC, heavy plugins, huge job histories Thread dumps (/threadDump), GC logs, Monitoring plugin, prune history
Build fails only on one agent Snowflake agent with different tools Ephemeral, image-defined agents
"Scripts not permitted to use method ..." Sandbox blocked a method Use a pipeline step instead, or admin approves narrowly; move logic into a trusted library carefully
NotSerializableException Non-serializable object held across a CPS step Move code into a @NonCPS method; don't keep matchers/iterators across steps
Webhook not triggering Jenkins unreachable from GitHub, wrong URL/secret, job not configured for webhook GitHub webhook delivery log, Jenkins /github-webhook/ endpoint, proxy/allow lists
Credentials not found Wrong ID or scope (folder credential used outside folder) Check credential scope and ID
Plugin upgrade broke Jenkins Incompatible plugin versions Roll back to the previous image (pinned plugins!), test upgrades on staging
Pipeline green but deploy broken No post-deploy verification Smoke tests, SLO checks, automated rollback

Useful places: Manage Jenkins → System Log, $JENKINS_HOME/logs, /threadDump, /manage/systemInfo, the agent's log page, and the script console (admins only) for diagnostics.

Enlarge diagramStuck in queuelabel, agents, pod eventsAgent dropsagent heap, disk, LB idle timeoutUI slow/threadDump, GC logs, history sizeWebhook silentGitHub delivery log,/github-webhook/Credential not foundID and folder scopePlugin broke itroll back to the pinned image
Figure 1. Where to look first when Jenkins misbehaves.
Swipe sideways to see all of it, or tap to open it full screen.