Fix Guide

How to Fix ServiceNow MID Server Disconnected or Stuck Queue

Step-by-step fix guide with AI-powered diagnosis from BuildForce.

ServiceNow MID server disconnects cause integration and discovery work to stall in the ECC queue. The fix workflow: check the MID server's Last Refreshed timestamp in ecc_agent (older than 1 minute = unhealthy), inspect the MID server's wrapper.log and agent0.log.0 files for the disconnect reason (Java OOM, keystore cert expiry, network reachability), restart the MID server service, and drain the backed-up ECC queue once heartbeat resumes. Repeated disconnects often indicate an undersized JVM heap or a corporate firewall dropping idle connections.

Heartbeat Failurewrapper.logKeystore ExpiryQueue Drain

Get AI-Powered Diagnosis See Pricing

Symptoms

ecc_agent showing Last Refreshed timestamp >1 minute old for one or more MID servers

ECC queue accumulating entries in 'ready' state with topic matching the disconnected MID

Discovery jobs failing with 'No MID server available' for normally-discoverable IPs

MID server wrapper.log showing OutOfMemoryError or 'Connection refused'

MID server going up briefly after restart then disconnecting again within minutes

Validation status showing 'Validation Required' after a ServiceNow instance upgrade

Root Causes

Java keystore certificate expired

MID server uses Java keystores for HTTPS to the ServiceNow instance and to discovered targets. When the keystore certificate expires, all SSL handshakes fail. wrapper.log shows 'PKIX path building failed' or 'certificate expired'.

JVM heap exhausted by large discovery job

A large discovery pattern (10,000+ targets) can exhaust the MID server's JVM heap. Default heap is 1GB which is undersized for production. wrapper.log shows OutOfMemoryError and the MID server crashes, restarting only to fail again.

Corporate firewall dropping idle MID-to-instance connections

MID servers maintain long-lived HTTPS connections to the ServiceNow instance. Corporate firewalls with idle-connection timeouts (often 60 minutes) drop these. MID server reconnects but the gap causes ECC queue backup during the window.

MID server requires re-validation after instance upgrade

After a ServiceNow instance upgrade, MID servers need re-validation. If the MID server's user account lacks the mid_server role or the new instance version requires re-acknowledgement, the MID stays in 'Validation Required' and doesn't process work.

MID server upgrade failed mid-process

When ServiceNow pushes an upgrade to the MID server, a failure mid-process can leave the agent in a broken state — old version files mixed with new, service starts but heartbeat fails. The upgrade.log shows the exact failure point.

How to Fix It — Step by Step

Check MID server status and heartbeat

Navigate to MID Server → Servers. Verify Status=Up and Last Refreshed < 1 minute old. Anything older is unhealthy. Click into the MID server to see its current state and validation status.

Example

GET /api/now/table/ecc_agent?sysparm_query=status=Down^ORlast_refreshed<javascript:gs.minutesAgoStart(2)&sysparm_fields=name,status,last_refreshed,validated

Inspect wrapper.log on the MID server host

On the MID server host, open <mid_install_dir>/agent/logs/wrapper.log. Search for ERROR or FATAL entries from the disconnect time. Common patterns: OutOfMemoryError (heap issue), PKIX path building failed (cert issue), Connection refused (network issue).

Check ECC queue backlog

Quantify the impact of the disconnect by counting stuck ECC queue entries. This tells you how much catch-up work the MID server has when it reconnects.

Example

GET /api/now/table/ecc_queue?sysparm_query=state=ready^agent=mid.server.YOUR_MID_NAME&sysparm_count=true

Restart the MID server service

On the MID server host: Windows — restart the 'ServiceNow MID Server' Windows service. Linux — run /etc/init.d/mid restart or systemctl restart mid. Monitor wrapper.log during startup to confirm clean initialization.

Renew keystore certificates if expired

If wrapper.log shows PKIX or cert expiry errors, the keystore needs renewal. Generate a new keystore using the MID server's config wizard or import the new certs into <mid_install_dir>/agent/security/cacerts. Restart the service after import.

Example

# Import a new cert into the MID server keystore
keytool -import -trustcacerts -alias servicenow_instance -file new_cert.pem -keystore <mid_install_dir>/agent/security/cacerts -storepass changeit

Increase JVM heap for large workloads

Edit <mid_install_dir>/agent/conf/wrapper-override.conf. Set wrapper.java.maxmemory=4096 (or 8192 for very large discoveries). Restart the service. Production MID servers should never run on default 1GB heap.

Example

# In wrapper-override.conf
wrapper.java.maxmemory=4096
wrapper.java.initmemory=2048

Drain the ECC queue after heartbeat resumes

Once the MID server is back up, the ECC queue processes the backlog automatically. Monitor the count dropping in 5-minute intervals. If the backlog isn't shrinking, restart the MID server again — there may be a poison-pill message blocking the queue.

Let BuildForce diagnose and fix this automatically

Instead of following manual steps, connect your org and let our AI identify exactly what's broken and how to fix it — in minutes.

Book a Demo

Common Questions

More answers about this issue and how to resolve it.

Stop debugging manually. Let AI do it.

BuildForce runs 200+ automated checks across your Salesforce org and tells you exactly what's broken and how to fix it.

Book a Demo View Pricing