Common Issues

This page covers frequently encountered problems and their solutions.

Password Reset

If you have lost the administrator password or locked out all accounts, you can reset the built-in system account using the nxdbmgr utility.

The server must be stopped while performing the password reset operation.

Using nxdbmgr

Linux
systemctl stop netxms-server
nxdbmgr reset-system-account
systemctl start netxms-server
Windows
net stop NetXMSCore
nxdbmgr reset-system-account
net start NetXMSCore

The command asks for confirmation, then unlocks the system account, sets a new random password, and prints that password to the terminal. The account is also flagged to require a password change at first login.

After resetting:

  1. Log in as system with the password printed by nxdbmgr (you will be asked to change it)

  2. In Configuration > Users and groups, change the password for your admin user account

  3. Log in as the admin user

  4. Disable the system account

Do not leave the system account enabled after recovery.

Locked Account Recovery

If an account is locked due to too many failed login attempts but an administrator password is known, log in as the administrator and unlock the account through Configuration > Users and groups. If no administrator can log in, stop the server and unlock the account with nxdbmgr unlock-user <login>.

Account locking is controlled by the Server.Security.IntruderLockoutThreshold server configuration variable (failed attempts before lockout; default 0 = locking disabled). The lockout duration is set by Server.Security.IntruderLockoutTime (minutes, default 30).

Server Will Not Start

Database Connection Errors

If the server fails to start with database connection errors:

  1. Verify the database server is running

  2. Check connection parameters in netxmsd.conf (DBDriver, DBServer, DBName, DBLogin, DBPassword)

  3. Test the database connection manually:

    PostgreSQL
    psql -h <db-server> -U <db-user> -d <db-name>
    MySQL/MariaDB
    mysql -h <db-server> -u <db-user> -p <db-name>

  4. Check that the database driver file exists in the server library directory

  5. Verify firewall rules allow connections from the NetXMS server to the database server

Port Already in Use

If the server reports that the listening port is already in use:

  1. Check if another instance of netxmsd is already running:

    ps aux | grep netxmsd

  2. Check what process is using the port:

    ss -tlnp | grep 4701

  3. Stop the conflicting process, or change the client listener port (server configuration variable Client.ListenerPort, default 4701) or the bind address (ListenAddress in netxmsd.conf)

Crash Dumps (Windows)

When running on Windows, the server can create crash dumps. To enable crash dump generation, add the following to netxmsd.conf:

CreateCrashDumps = yes
DumpDirectory = C:\NetXMS\crash

DumpDirectory must point to a directory writable by the server process. After each crash, the server creates an info file (basic crash information and call stack) and an mdmp file (minidump for debugger analysis).

A crash dump can also be forced from the server debug console using the dump command (Windows only) or raise access, which crashes the server on any platform; the dump file is still created on Windows only (on other systems, rely on OS core dumps if enabled).

When reporting crashes to the development team, provide:

  • The crash dump file

  • The server log file with debug level 1 or above

  • The server version (netxmsd -v)

  • Operating system and version

  • Database type and version

Agent Connection Issues

Agent Not Responding

If the server cannot communicate with an agent:

  1. Verify the agent is running on the target system:

    systemctl status netxms-agent

  2. Check that the agent is listening:

    ss -tlnp | grep 4700

  3. Test connectivity from the server to the agent:

    nxget <agent-host> Agent.Version

  4. Check firewall rules — port 4700/TCP must be open from server to agent for direct connections, or port 4703/TCP from agent to server for tunnel connections

  5. Verify the server’s IP is in the agent’s MasterServers list in nxagentd.conf

  6. Check for shared secret mismatch between server and agent configuration

Agent Tunnel Issues

For agents using tunnel connections:

  1. Check tunnel status in the management client under Configuration > Agent tunnels

  2. Verify the ServerConnection address is correct in nxagentd.conf:

    ServerConnection = <server-address>
MasterServers = <server-address>

  3. If using certificates, verify the certificate chain is valid and not expired

  4. Check the agent log for TLS handshake errors

SNMP Issues

SNMP Not Working

If NetXMS cannot collect SNMP data from a device:

  1. Verify SNMP is enabled on the target device

  2. Check the SNMP community string or v3 credentials configured on the node object match the device configuration

  3. Verify access control on the device or firewall allows connections from the NetXMS server

  4. Test SNMP connectivity from the NetXMS server:

    snmpwalk -v2c -c <community> <target-ip> system

  5. Check that UDP port 161 is open between the server and the target device

  6. For SNMPv3, verify that the authentication and privacy settings match exactly (protocol, password, engine ID)

  7. If a device is not recognized as SNMP-capable, it may not respond to the OIDs probed during detection: sysObjectID (.1.3.6.1.2.1.1.2.0) and sysDescr (.1.3.6.1.2.1.1.1.0), plus driver-specific OIDs. Set the node custom attribute snmp.testoid to any OID supported by the device to override the detection OID.

SNMP Traps Not Received

If SNMP traps are not being received:

  1. Verify the NetXMS server is configured to listen for traps (default port 162)

  2. Check that the trap sender is configured to send traps to the NetXMS server IP

  3. Verify no other application (e.g., snmptrapd) is already bound to UDP port 162:

    ss -ulnp | grep 162

  4. Check the server log for trap processing errors (enable debug tag snmp.trap)

  5. Ensure the sending device exists as a node in NetXMS — traps from unknown sources are discarded by default

Data Collection Issues

DCI Reports Data Collection Errors

A data collection error (shown in Last Values as consecutive collection failures, or a DCI switching to Not supported status) indicates the server was unable to retrieve the metric value.

Common causes:

  • Agent is unreachable — check agent connectivity (see Agent Not Responding)

  • Metric name is incorrect — for agent metrics, verify the exact name with nxget -I <host> or the metric selection dialog in the DCI editor

  • SNMP OID does not exist on the device — open MIB Explorer from the node context menu and use its Walk action to verify

  • Web service endpoint is unreachable or returning unexpected data

  • Transformation script has a runtime error — check the server log for script errors (logged under the scripts debug tag)

Historical Data Gaps

If you see gaps in historical data:

  • Check if the server was running during the gap period

  • Verify the DCI polling interval has not been changed

  • Check that the DCI’s retention time is not causing premature data deletion (a DCI uses either its own retention time or, when set to Server default, the current value of the DataCollection.DefaultDCIRetentionTime server configuration variable — lowering that variable shortens retention for all such DCIs at the next housekeeper run)

  • Look for database-related warnings in the server log during the gap period

  • For SNMP-based DCIs, check if the target device was unreachable during that period

Web Management Console Issues

Cannot Connect to Web Console

If the web management console is not accessible:

  1. Verify the web server (Tomcat, Jetty, or application server) is running

  2. Check that the web console configuration (nxmc.properties or other configuration sources) points to the correct NetXMS server address — see Web Console Configuration

  3. Verify the server is accepting client connections on port 4701

  4. Check the web application logs for connection errors

  5. If using HTTPS, verify the TLS certificate is valid and not expired

Autologin for Management Client

The management client supports automatic login for scenarios such as kiosk displays, NOC screens, and unattended dashboards.

For detailed autologin configuration, including command-line parameters and security considerations, see Autologin for Management Client in the User Management section.

Performance Issues

Server Running Slowly

If the NetXMS server becomes slow or unresponsive:

  1. Check CPU and memory usage of the netxmsd process

  2. Monitor thread pool utilization using the Server.ThreadPool.* internal metrics on the management server node (e.g., Server.ThreadPool.Load(POLLERS), Server.ThreadPool.Usage(DATACOLL))

  3. Check the database server performance — slow queries often cause overall slowness

  4. Review the number of monitored nodes and DCIs — ensure thread pool sizes are adequate:

    Configuration Variable

    Purpose

    ThreadPool.Poller.MaxSize

    Increase for large-scale environments (default: 250)

    ThreadPool.DataCollector.MaxSize

    Increase if data collection queues are backing up (default: 250)

  5. Enable debug tag db.query temporarily to identify slow database queries

  6. Check disk I/O on the database server

For detailed information on debug logging and diagnostics, see Diagnostics. For debug console commands, see Debug Console.