> For the complete documentation index, see [llms.txt](https://docs.netmap.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.netmap.dev/troubleshooting/database-problems.md).

# Database Problems

NetMap uses `netmap.db` and `firewall.db`.

Startup validates `DATA_DIR` exists and is writable. Firewall database corruption has specific recovery paths in `firewall_session.py`.

Before any manual database action, create a backup.

## Symptoms

* Container exits during startup.
* UI loads but inventory or topology data is missing.
* Security/syslog search fails or returns no data.
* Logs mention malformed SQLite schema, database disk image errors, locked database, or permission denied.
* Admin diagnostics show unexpected database sizes.

## Confirm The Data Directory

```bash
docker compose exec netmap sh -c 'ls -lah /app/data && test -w /app/data'
```

If this fails, the container user cannot write to the mounted volume.

## Confirm Container Logs

```bash
docker compose logs --tail=200 netmap
```

Search for database messages:

```bash
docker compose logs netmap | grep -Ei "sqlite|database|malformed|locked|permission"
```

## Main Database Versus Firewall Database

`netmap.db` stores core application state. Problems here can affect login, inventory, topology, monitoring, IPAM, settings, roles, and API keys.

`firewall.db` stores firewall/syslog events. Problems here should primarily affect Security/syslog features. The source includes recovery handling for certain firewall DB and FTS corruption cases.

## Common Fixes

| Cause                                   | Fix                                                                               |
| --------------------------------------- | --------------------------------------------------------------------------------- |
| `/app/data` not writable                | Fix host ownership or set correct `PUID`/`PGID`.                                  |
| Live backup copied without WAL sidecars | Restore from a stopped-container backup or include `.db-wal` and `.db-shm`.       |
| Disk full                               | Free host disk space, then restart.                                               |
| Firewall FTS corruption                 | Restart and review logs; FTS rebuild handling exists for shadow-table corruption. |
| Main database corruption                | Restore from backup.                                                              |

## Verify Recovery

```bash
curl --fail http://127.0.0.1:8080/api/health
```

Then sign in and check the affected workspace.

## Related Pages

* [Storage](/configuration/storage.md)
* [Backups](/operations/backups.md)
* [Restores](/operations/restores.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.netmap.dev/troubleshooting/database-problems.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.