Troubleshooting

Log Files

The primary diagnostic tool is agent.log located in the installation directory. Log format:

<PID> | <datetime> | <Level> | <message>

Log Rotation

Serilog handles log rotation automatically:

When agent.log exceeds 10MB, it rolls to agent_001.log, agent_002.log, etc.
Number of retained files is configurable via RetainedLogs (default: 3). Oldest files are permanently deleted (skips recycle bin).
Logs are appended across restarts — never wiped

Windows Event Log

Warnings and Errors are also written to the Windows Application event log under source JenkinsAsService. Check this when:

The file log is missing or corrupted
The service crashed before writing to the file
You need crash evidence across multiple restarts

Get-EventLog -LogName Application -Source JenkinsAsService -Newest 20

Common Issues

Service starts and immediately stops

Check agent.log for:

Log Message	Cause	Fix
`Mandatory fields (JenkinsURL, AgentSecret) are empty`	Config not filled in	Edit `appsettings.json` and fill the `Jenkins` section
`'JenkinsURL' is a mandatory field`	`JenkinsURL` empty	Set the Jenkins URL in `appsettings.json`
`'AgentSecret' is a mandatory field`	`AgentSecret` empty	Copy the secret from Jenkins node configuration
`JenkinsURL must include an explicit port`	URL uses default port (80/443)	Add an explicit port, e.g. `https://jenkins.example.com:8443`

Java not found

Log Message	Cause	Fix
`Cannot find java.exe. Set 'JavaPath' in appsettings.json or the JAVA_HOME environment variable.`	No Java configured	Set `JavaPath` in config or set `JAVA_HOME` system environment variable. Path should point to the JDK `bin` folder.

Connection failures

Log Message	Cause	Fix
`Cannot reach Jenkins at '...' on port ... (timed out)`	Jenkins unreachable / timeout	Check firewall, DNS, and that Jenkins is running
`Cannot reach Jenkins at '...' on port ...: <socket error>`	Connection refused or DNS failure	Verify URL, port, and network connectivity

Download failures

Symptom	Cause	Fix
HTTP error in log during download	Jenkins URL wrong or controller down	Verify `JenkinsURL` is correct and Jenkins is running
`agent.jar` download hangs	Network issues / proxy	Check connectivity, consider adding proxy config to `HttpClient`

Agent connects but disconnects randomly

Check watchdog log entries: search for Watchdog: in agent.log
The watchdog will auto-recover with exponential backoff
If Watchdog: Max retries (N) exceeded appears, the issue is persistent — check:
- AgentName matches the node name in Jenkins exactly (case-sensitive)
- AgentSecret is correct (regenerate in Jenkins if unsure)
- Jenkins controller logs for rejection reasons
- Network stability between the agent and controller

Watchdog keeps restarting

If the agent repeatedly dies and recovers:

Enable DebugMode: true for detailed Java output
Look for patterns in agent.log — the watchdog logs exit codes before each restart
Common causes: Java OOM (increase heap via CustomArguments), Jenkins controller restarts, network drops

Debug Mode

Set DebugMode to true in appsettings.json to enable verbose Java agent output in the log file. This captures all Java stdout/stderr including remoting/JNLP handshake details.

Note

Debug mode is set at startup via Serilog minimum level. A service restart is required to toggle it.

Service Recovery (Windows-Level)

The built-in watchdog handles Java process crashes. For full service host crashes (the .NET process itself dying), the MSI installer configures Windows service recovery automatically:

First / Second / Third failure: Restart the Service (after 10 seconds)
Reset fail count after: 1 day

This is set via util:ServiceConfig in Service.wxs during installation — no manual configuration needed.