Jenkins troubleshooting

Build fails immediately / cannot checkout SCM

Git credential missing, wrong branch, or host key verification failed. Check job SCM config and credential ID in the Jenkinsfile. Test SSH from the agent: git ls-remote. For HTTPS, use username/password or token credential. Webhook not firing is separate — verify repo hook URL and Jenkins reachable from Git server.

Agent offline / no executors available

UI shows agent red or builds stuck in queue. SSH agent: check network, Java on agent, and agent.jar connection. Docker/K8s agents: verify cloud plugin config and image pull. Controller built-in executor count may be zero by design — assign jobs to labeled agents. Restart agent or delete and reconnect node.

Pipeline syntax / Groovy error

Declarative pipeline errors appear in Console Output with line hints. Validate in **Pipeline Syntax** generator (UI). Common issues: stages outside pipeline { }, wrong indentation in Declarative, calling non-serializable objects in pipeline. Use script { } block for complex Groovy in Declarative.

Credentials not found

Could not find credentials entry with ID 'xxx' — ID mismatch between Jenkinsfile and Credentials store, or credential scoped to wrong folder. Domain-specific credentials need matching folder job. Check spelling and whether credential is on the controller visible to the job.

Docker / permission denied in pipeline

Agent user not in docker group or DinD socket not mounted. For Kubernetes agents, check service account and privileged mode requirements. See Docker lab. Harbor push failures often need withCredentials and correct registry URL.

Disk full on controller

JENKINS_HOME workspaces, artifacts, and old builds consume disk. Configure **Discard old builds** on jobs. Run workspace cleanup scripts; du -sh /var/lib/jenkins/*. Plugin logs and fingerprints also grow. See disk volumes lab.

Jenkins won’t start after upgrade

Incompatible plugins or Java version mismatch. Jenkins LTS requires supported Java (11 or 17+ depending on version). Check journalctl -u jenkins -e. Start with --httpPort=8080 in foreground for stack trace. Roll back plugin versions via plugins/*.jpi backup or restore JENKINS_HOME snapshot.

Slow or hanging builds

Stuck on a step — check Console Output last line. Add stage timeouts. Network waits (npm, apt, docker pull) dominate. Executor starvation: too few agents for parallel jobs. Thread dump from /monitoring/threads (admin) if UI is sluggish.

Debugging workflow

1. Build console

2. Agent and queue

3. Server logs