This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

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)

Server Crashes and Hangs

Crash Dumps (Windows)

When running on Windows, the server creates a crash dump when it crashes. This is on by default (CreateCrashDumps = yes). Dumps are written to DumpDirectory, which defaults to C:\; set it to a dedicated directory in netxmsd.conf:

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 for debugger analysis. The .mdmp file holds the full process memory; with FullCrashDumps = no it is a smaller minidump.

A crash dump can also be forced from the server debug console. The dump command writes a dump of the running process without stopping it (Windows only). On Linux, capture the crash as described in Crash Capture (Linux).

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

Crash Capture (Linux)

On Linux, the server does not write crash dump files: CreateCrashDumps and DumpDirectory have no effect. To get the call stack of a crash, run the server under the gdb debugger and reproduce the crash.

  1. Install gdb and the debug symbol packages. Without debug symbols, the call stack is incomplete and shows memory addresses without file and line information.

    Debian/Ubuntu
    sudo apt install gdb netxms-dbg
    RHEL/AlmaLinux/Fedora
    sudo dnf install gdb netxms-base-debuginfo netxms-server-debuginfo netxms-dbdrv-pgsql-debuginfo

    On RHEL/AlmaLinux/Fedora, replace netxms-dbdrv-pgsql-debuginfo with the package for your database driver. The debug symbol packages must have the same version as the installed NetXMS packages.

  2. Stop the server service:

    sudo systemctl stop netxms-server
  3. Start gdb with the server command line:

    sudo gdb -ex 'set pagination off' -ex 'set logging file /tmp/netxmsd-crash.txt' -ex 'set logging on' --args /usr/bin/netxmsd -q -D 1

    Without -d or -S, the server runs in the foreground. -q disables the interactive server console, which otherwise competes with gdb for terminal input. -D 1 sets debug level 1. If the server uses a configuration file in a non-default location, add -c <file>. For a source installation, use the netxmsd binary from your installation prefix. If the crash can take a long time to reproduce, run gdb in a tmux or screen session, so that the server keeps running when you disconnect.

  4. At the (gdb) prompt, start the server:

    run
  5. Reproduce the crash. When the server crashes, gdb stops it and shows the signal, for example received signal SIGSEGV, Segmentation fault.

  6. Print the call stack of the crashed thread, then the call stacks of all threads:

    bt
    thread apply all bt

    gdb writes this output to /tmp/netxmsd-crash.txt.

  7. Type quit and confirm with y to end the server process, then start the service again:

    sudo systemctl start netxms-server

To test the procedure, send the server a segmentation fault signal from another terminal while it runs under gdb: sudo kill -SEGV $(pidof netxmsd). gdb stops the server as it would on a real crash.

When reporting the crash to the development team, provide:

  • The file /tmp/netxmsd-crash.txt

  • The server log file with debug level 1 or above

  • The server version (netxmsd -v)

  • Operating system and version

  • Database type and version

Using systemd-coredump

If systemd-coredump collects core dumps on the system (/proc/sys/kernel/core_pattern refers to systemd-coredump), the server can stay under the control of its service. The service units in the official Debian and RPM packages allow core dumps (LimitCORE=infinity); for a source installation or a custom unit, check the core dump limit of the service. After a crash, install the debug symbol packages from step 1 and open the most recent server core dump in gdb:

sudo coredumpctl gdb netxmsd

At the (gdb) prompt, save the call stacks to a file:

set pagination off
set logging file /tmp/netxmsd-crash.txt
set logging on
bt
thread apply all bt

A large server process can exceed the core dump size limits in /etc/systemd/coredump.conf. If no core dump is stored, check these limits.

Thread Dumps (Linux)

When the server or the agent stops responding or uses too much CPU, a thread dump shows the call stack of every thread. The process pauses briefly while the stacks are captured and then continues; it is not terminated or restarted.

The scripts capture_netxmsd_threads.sh (server) and capture_nxagentd_threads.sh (agent) in the tools directory of the NetXMS source tree create the thread dump. They need gdb and the debug symbol packages listed in Crash Capture (Linux). For the agent on RHEL/AlmaLinux/Fedora, install netxms-base-debuginfo and netxms-agent-debuginfo.

Download the script and run it as root (for the agent, use capture_nxagentd_threads.sh):

curl -sSLO https://raw.githubusercontent.com/netxms/netxms/master/tools/capture_netxmsd_threads.sh
sudo sh capture_netxmsd_threads.sh

The script attaches gdb to the running process, writes the call stacks of all threads to a file in /tmp, and detaches. It prints the name of the file:

Saving output to /tmp/netxmsd-threads.12345.20260708-142530

Run the script three times, 20 to 30 seconds apart, so that the support team can compare the dumps and see which threads are stuck.

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. By default, all these OIDs are sent in one GET request. The check accepts a response whose PDU error status is noError or noSuchName; another PDU error status, or no response, fails it. SNMPv2c/v3 noSuchObject and noSuchInstance values for individual OIDs do not fail the check. Set the node custom attribute snmp.testoid to an OID the device supports: the configuration poll prepends it to the list of test OIDs, but it does not replace the other OIDs. If the device answers requests containing OIDs it does not implement with a PDU error, also set the server configuration variable SNMP.Discovery.SeparateProbeRequests to 1, so that each OID is sent in its own request and probing stops at the first accepted response. This variable is global: it applies to the configuration polls of all nodes and to network discovery.

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 indicates the server was unable to retrieve a usable metric value. Last Values shows the reason of the last failed collection in place of the value: << COMM ERROR >> (source not reachable), << NOT SUPPORTED >> (metric unknown to the source), << NO SUCH INSTANCE >>, << ACCESS DENIED >>, << INVALID DATA >> (value collected but not usable), or << ERROR >> for any other failure. A DCI can also switch to Not supported status.

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 — select Open > MIB Explorer in 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.