# Mongonaut: Self-Hosted MongoDB Web GUI

## Troubleshooting

> Category: Guides

---

## Pages

- [Overview](https://mongonaut.org/about-mongonaut)
- [Installation](https://mongonaut.org/installation)
- [Docker setup](https://mongonaut.org/mongodb-gui-docker)

### Compare

- [Mongonaut vs mongo-express](https://mongonaut.org/compare/mongonaut-vs-mongo-express)
- [Mongonaut vs MongoDB Compass](https://mongonaut.org/compare/mongonaut-vs-mongodb-compass)

### Guides

- [Migrate from mongo-express](https://mongonaut.org/guides/migrate-from-mongo-express)
- [Read-only configuration](https://mongonaut.org/guides/read-only-configuration)
- [Troubleshooting](https://mongonaut.org/guides/troubleshooting)

### Security

- [Authentication](https://mongonaut.org/security/authentication)
- [Cloudflare Zero Trust Tunnel](https://mongonaut.org/security/zero-trust-tunnel)

### Community

- [FAQ](https://mongonaut.org/community/faq)
- [Contributing](https://mongonaut.org/community/contributing)

---

# Troubleshooting

Use this guide when Mongonaut starts but cannot connect to MongoDB, authentication does not behave as expected, or Docker networking causes confusing connection errors.

## Prerequisites

- Access to container logs.
- The current `docker run` command or Docker Compose file.
- The value of `MONGO_CONNECTION_URL` without secrets when asking for help.
- The Mongonaut version, if available.

Check logs first:

```bash
docker logs <mongonaut-container>
```

With Docker Compose:

```bash
docker compose logs mongonaut
```

## Connection problems

### `getaddrinfo ENOTFOUND mongo`

The hostname `mongo` cannot be resolved from inside the Mongonaut container.

Fixes:

- Put Mongonaut and MongoDB in the same Docker Compose network.
- Use the MongoDB service name as the hostname.
- Replace `mongo` with a reachable hostname or IP address.

Working Compose pattern:

```yaml
services:
  mongo:
    image: mongo:latest
    networks:
      - mongo-network

  mongonaut:
    image: ghcr.io/withzu/mongonaut
    environment:
      MONGO_CONNECTION_URL: mongodb://mongo:27017/
    networks:
      - mongo-network

networks:
  mongo-network:
    driver: bridge
```

### `ECONNREFUSED 127.0.0.1:27017`

Inside a container, `127.0.0.1` points to that container, not your host machine.

Use one of these instead:

```env
MONGO_CONNECTION_URL=mongodb://mongo:27017/
MONGO_CONNECTION_URL=mongodb://host.docker.internal:27017/
MONGO_CONNECTION_URL=mongodb://192.0.2.10:27017/
```

### MongoDB Atlas timeout

Check:

- The Atlas access list includes the server or network running Mongonaut.
- The `mongodb+srv://` URI is copied correctly.
- Username and password are URL-encoded when they contain special characters.
- The database user has permission to read the databases you expect.

## Authentication problems

### Missing `MONGONAUT_AUTH_SECRET`

Every authentication mode except `NONE` requires a signing secret.

```bash
openssl rand -base64 32
```

Set it:

```env
MONGONAUT_AUTH_SECRET=<generated value>
```

### `/setup` redirects to `/login`

An account already exists. Use `/login`. If the administrator password is lost, run the recovery command:

```bash
docker exec <container> node scripts/recovery.mjs admin@example.com
```

### OIDC callback mismatch

Set the public callback URL explicitly:

```env
MONGONAUT_OIDC_REDIRECT_URL=https://mongonaut.example.com/api/auth/oidc/callback
```

Register the same URL in the identity provider.

### Static password does not work

Check that both variables are set:

```env
MONGONAUT_AUTH_MODE=STATIC_PASSWORD
MONGONAUT_AUTH_PASSWORD=<shared password>
```

Also keep `MONGONAUT_AUTH_SECRET` configured.

## Read-only and permission problems

### Write actions are disabled

Check for instance-wide read-only mode:

```env
MONGONAUT_READONLY=true
```

Also check account grants in `ACCOUNT` mode and MongoDB user permissions.

### Expected databases are missing

Possible causes:

- The MongoDB user in `MONGO_CONNECTION_URL` does not have permission.
- Account mode grants do not include the database or collection.
- Internal MongoDB databases may be hidden from the navigation.

### Write fails even though buttons are visible

The MongoDB user may not have write permissions. Mongonaut can only perform operations allowed by the database credentials it uses.

## Docker and port problems

### Port `8081` is already in use

Publish Mongonaut on another host port:

```yaml
ports:
  - 8082:8081
```

Then open:

```text
http://localhost:8082
```

### Reverse proxy or tunnel returns 502

The proxy cannot reach Mongonaut. Verify the upstream URL from the proxy's point of view.

Examples:

```text
http://localhost:8081
http://mongonaut:8081
```

When the proxy runs in Docker, `localhost` usually points to the proxy container itself.

## Useful checks

Show running containers:

```bash
docker ps
```

Show Compose services:

```bash
docker compose ps
```

Check environment variables in a running container:

```bash
docker exec <mongonaut-container> env | sort
```

Do not share secrets from this output publicly.

## Related links

- [Install Mongonaut](/installation)
- [MongoDB GUI with Docker](/mongodb-gui-docker)
- [Authentication](/security/authentication)
- [Cloudflare Zero Trust Tunnel](/security/zero-trust-tunnel)
- [Read-only configuration](/guides/read-only-configuration)