Troubleshooting

This is a collection of some common issues and how to resolve them. If your issue is not here, look through the existing issues and eventually create a new issue.

Docker Compose basics

See all running containers:

docker compose ps

See all logs:

docker compose logs -f

See just the NetBox logs:

docker compose logs -f netbox

Stop it all:

docker compose stop

Reset the project:

⚠️ This will remove any Netbox-related data.

docker compose down -v --remove-orphans
git reset --hard origin/release

Bash

Start the Netbox Container shell, e.g. to get access to ./manage.py or look for files:

docker compose exec netbox /bin/bash

To load the Python environment for Netbox run:

source /opt/netbox/venv/bin/activate

Database Operations

Access the database:

docker compose exec postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'

Take a database backup

docker compose exec -T postgres sh -c 'pg_dump -cU $POSTGRES_USER $POSTGRES_DB' | gzip > db_dump.sql.gz

Restore that database:

# Stop all NetBox instances that access the db
docker compose stop netbox netbox-worker netbox-housekeeping

# Restore the DB dump
gunzip -c db_dump.sql.gz | docker-compose exec -T postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'

File Operations

Backup of the media directory, which contains uploaded images.

docker compose exec -T netbox tar c -jf - -C /opt/netbox/netbox/media ./ > media-backup.tar.bz2

Restore of the media directory:

⚠️ This may overwrite files in the media directory!

docker compose exec -T netbox tar x -jvf - -C /opt/netbox/netbox/media < media-backup.tar.bz2 

Netbox Worker Operations

See the status of the worker queue:

docker compose run --rm netbox-worker /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py rqstats

Netbox Shell (nbshell)

The nbshell is a way to quickly get programmatic access to Netbox. It offers about the same interface as the Netbox REST API.

docker compose run --rm netbox /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py nbshell

Frequently Asked Questions (FAQ) and Common Problems

Getting to "process X exited with code 0"

You find yourself with a NetBox Docker instance that tells you something like:

[notice] 7#7 process 14 exited with code 0

Congratulations! Your NetBox Docker instance most definitely started successfully. Your problem is probably somewhere else, if there's even a problem.

While starting, Django (the Python framework that powers NetBox) creates several child processes. After a successful start, some of these child processes do exit. As long as it states that the exit code is 0, all is well: The exit code 0 in Unix/Linux-land (usually) indicates a success.

Getting a "Bad Request (400)"

When connecting to the Netbox instance, I get a "Bad Request (400)" error.

This usually happens when the ALLOWED_HOSTS variable is not set correctly.

How to upgrade

How do I update to a newer version of netbox?

⚠️ Make sure to take a database backup first.

💡 Read the release notes. They include important update information.

Update your local installation:

# Update the configuration files
git pull origin release

# Fetch the newest containers
docker compose rm -fs netbox netbox-worker
docker compose pull
docker compose up -d netbox netbox-worker

Webhooks don't work

First make sure that the webhooks feature is enabled in your Netbox configuration and that a redis host is defined. Check netbox.env if the following variables are defined:

WEBHOOKS_ENABLED=true
REDIS_HOST=redis

Then make sure that the redis container and at least one netbox-worker are running.

# check the container status
$ docker compose ps

Name                           Command               State                Ports
--------------------------------------------------------------------------------------------------------
netbox-docker_netbox-worker_1   /opt/netbox/docker-entrypo ...   Up
netbox-docker_netbox_1          /opt/netbox/docker-entrypo ...   Up      80/tcp, 0.0.0.0:32776->8080/tcp
netbox-docker_postgres_1        docker-entrypoint.sh postgres    Up      5432/tcp
netbox-docker_redis_1           docker-entrypoint.sh redis ...   Up      6379/tcp

# connect to redis and send PING command:
$ docker compose run --rm -T redis sh -c 'redis-cli -h redis -a $REDIS_PASSWORD ping'
Warning: Using a password with '-a' option on the command line interface may not be safe.
PONG

If redis and the netbox-worker are not available, make sure you have updated your docker-compose.yml file!

Everything's up and running? Then check the log of netbox-worker and/or redis:

docker compose logs -f netbox-worker
docker compose logs -f redis

Still no clue? You can connect to the redis container and have it report any command that is currently executed on the server:

docker compose run --rm -T redis sh -c 'redis-cli -h redis -a $REDIS_PASSWORD monitor'

# Hit CTRL-C a few times to leave

If you don't see anything happening after you triggered a webhook, double-check the configuration of the netbox and the netbox-worker containers, and also check the configuration of your webhook in the admin interface of NetBox.