Skip to content

Troubleshooting

Jump to bottom Edit New page
Oliver Gorwits edited this page Dec 28, 2025 · 24 revisions

Devices are not discovered

First of all, is the backend daemon running? Run the following command at the CLI to check:

~/bin/netdisco-backend status

Besides reading the whole of this manual page for general tips, take a look at the "SNMP Connect Failures" report under the Admin menu. Any devices listed have had multiple SNMP connect failures, indicating a possible configuration error on the device or in Netdisco’s configuration.

My Device details are wrong!

See the tips at Vendor Tips, or else read Troubleshooting Discovery.

Devices have the wrong names

Netdisco uses neighbor protocols to discover devices and will use as the default identity for a device the interface IP advertised over those neighbor protocols. You can use the device_identity configuration setting to steer Netdisco towards using a different interface for the canonical device name.

Missing MAC or IP addresses

First read the Concepts documentation. Then read Troubleshooting Discovery.

Can’t connect to TCP port 5000 on ::

This is resolved by setting the environment variable IPV=4.

It’s a problem with binding to server’s IP address, which reports IPv6 capability, when you are only using an IPv4 address.

In the netdisco logs, ~/logs/netdisco-web.log, you will see:

2024/08/29-14:55:55 Starman::Server (type Net::Server::PreFork) starting! pid(3862)
Resolved [*]:5000 to [::]:5000, IPv6
Not including resolved host [0.0.0.0] IPv4 because it will be handled by [::] IPv6
Binding to TCP port 5000 on host :: with IPv6
2024/08/29-14:55:55 Can't connect to TCP port 5000 on :: [Invalid argument]
  at line 66 in file /home/netdisco/perl5/lib/perl5/Net/Server/Proto/TCP.pm

This is resolved by setting the environment variable IPV to 4, before starting netdisco-web:

$ export IPV=4
$ /home/netdisco/bin/netdisco-web start

The content of IPV can be checked by:

$ printenv | grep IPV

It is advisable to set the IPV environment variable in your netdisco user’s .bashrc source script.

After OS update or upgrade, Netdisco fails

If you upgrade the operating system then your system libraries will change and Netdisco needs to be rebuilt (specifically, C library bindings which affects perl xs modules & other items).

The safest way to do this is set up a new user and follow the same install instructions, connecting to the same database. Stop the web and backend daemon for the old user, and start them for the new user. Then delete the old user account.

Alternatively, if you do not mind the downtime: stop the web and backend daemons then delete the ~/perl5 directory and reinstall from scratch. The configuration file, database, and MIBs can all be reused in-place.

Run a netdisco-do Task with Debugging

The netdisco-do command has several debug flags which will show what’s going on internally. Usually you always add -D for general Netdisco debugging, then -I for SNMP::Info logging and -Q for SQL tracing. For example:

~/bin/netdisco-do discover -d 192.0.2.1 -DIQ

You will see that SNMP community strings and users are hidden by default, to make the output safe for sending to Netdisco developers. To show the community string and SNMPv3 protocols, set the SHOW_COMMUNITY environment variable:

SHOW_COMMUNITY=1 ~/bin/netdisco-do discover -d 192.0.2.1 -DIQ

Dump an SNMP object for a Device

This is useful when trying to work out why some information isn’t displaying correctly (or at all) in Netdisco. It may be that the SNMP response isn’t understood. Netdisco can dump any leaf or table, by name:

~/bin/netdisco-do show -d 192.0.2.1 -e interfaces
~/bin/netdisco-do show -d 192.0.2.1 -e ::interfaces
~/bin/netdisco-do show -d 192.0.2.1 -e Layer2::HP::interfaces

You can combine this with SNMP::Info debugging, shown above (-I).

Interactive SQL terminal on the Netdisco Database

Start an interactive terminal with the Netdisco PostgreSQL database. If you pass an SQL statement in the "-e" option then it will be executed.

~/bin/netdisco-do psql
~/bin/netdisco-do psql -e 'SELECT ip, dns FROM device'
~/bin/netdisco-do psql -e 'COPY (SELECT ip, dns FROM device) TO STDOUT WITH CSV HEADER'

The last example above is useful for sending data to Netdisco developers, as it’s more compact and readable than the standard tabular output (second example).

See how Netdisco has parsed the Configuration File

At the command line you can dump the complete parsed configuration or one configuration setting (replace settingname with the setting key):

~/bin/netdisco-do dumpconfig
~/bin/netdisco-do dumpconfig -e settingname

Note that the device_auth and snmp_auth settings are not dumped by default. They can be retrieved for a specific device:

~/bin/netdisco-do dumpconfig -d 192.0.2.1 -e device_auth

Change the SNMP community string for a Device

If you change the SNMP community string in use on a Device, and update Netdisco’s configuration to match, then everything will continue to work fine.

However, if the Device happens to support two community strings then Netdisco can become "stuck" on the wrong one, as it caches the last-known-good community string to improve performance. To work around this, delete the device (either in the web GUI or using netdisco-do at the command line), and then re-discover it.

Database Schema Redeployment

The database schema can be redeployed (even over an existing installation), in a safe way, using the following command:

~/bin/netdisco-db-deploy --redeploy-all

To drop all tables and data from the database, and redeploy (including setting up an initial web user), run:

❗
 This is a destructive task! Backup your database first. 
~/bin/netdisco-do psql -e 'DROP OWNED BY netdisco'
~/bin/netdisco-deploy

Installation on SLES 11 SP4

Try running the following command for installation:

curl -L http://cpanmin.us/ | CFLAGS="-DPERL_ARGS_ASSERT_CROAK_XS_USAGE" perl - --notest --local-lib ~/perl5 App::Netdisco

perl-TermReadLine-Gnu operating system packages

certain versions of this package can make netdisco-deploy error out with:

Warning: unable to close filehandle properly: Bad file descriptor during global destruction.

upgrading to a newer version (1.35) should fix the problem. if this is not an option setting the environment variable PERL_RL=Perl can also work around the problem.

This documentation is copyright © 2026 by The Netdisco Developer Team.

Netdisco

Installing

Concepts

Tips and Tricks

Features

Developing

External Links

Clone this wiki locally