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

(Press Ctrl+C to return to the shell prompt.)

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 -zf - -C /opt/netbox/netbox/media ./ > media-backup.tar.gz

Restore of the media directory:

⚠️ This may overwrite files in the media directory!

docker compose exec -T netbox tar x -zvf - -C /opt/netbox/netbox/media < media-backup.tar.gz

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.

DBShell in Netbox container doesn't work

We don't install psql into the Netbox container. Because of this the command ./manage.py dbshell will not work. To access the database shell directly use the command mentioned under the section Database Operations.

Netbox Container doesn't start when IPv6 is disabled

You can disable the IPv6 listener in the container by replacing the Nginx Unit configuration. Make a copy of the the nginx-unit.json from our repository (from the tag you are using) and remove the IPv6 listener section:

    "[::]:8080": {
      "pass": "routes"
    }

NOTE: Also remove the trailing comma

After the section is removed you need to mount the new configuration file into the container. This can be done in a volumes section in docker-compose.override.yml with the following line:

- /opt/netbox/configuration/nginx-unit.json:/etc/unit/nginx-unit.json:ro