> 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/common-issues.md).

# Common Issues

Use this page as the first stop when NetMap is unhealthy or behaving unexpectedly.

## First Checks

Start with:

```bash
docker compose ps
docker compose logs --tail=200 netmap
curl --fail http://127.0.0.1:8080/api/health
```

Then use the issue-specific pages in this section.

## Triage By Symptom

| Symptom                                   | Start here                                                             |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| Container will not start                  | [Installation Problems](/troubleshooting/installation-problems.md)     |
| Login fails                               | [Authentication Problems](/troubleshooting/authentication-problems.md) |
| API key fails                             | [API-Key Problems](/troubleshooting/api-key-problems.md)               |
| API returns `403`                         | [Permission Errors](/troubleshooting/permission-errors.md)             |
| Data is missing or database errors appear | [Database Problems](/troubleshooting/database-problems.md)             |
| Works locally but not through domain      | [Reverse Proxy Problems](/troubleshooting/reverse-proxy-problems.md)   |
| Docker health is failing                  | [Container Problems](/troubleshooting/container-problems.md)           |
| Need to ask for support                   | [Diagnostic Information](/troubleshooting/diagnostic-information.md)   |

## Collect Safe Details

When asking for help, include:

* NetMap version;
* deployment method;
* exact URL path or workspace;
* HTTP status code;
* redacted `detail` response;
* relevant container logs.

Do not include passwords, tokens, API keys, OIDC secrets, or private key material.

## Related Pages

* [Health Checks](/operations/health-checks.md)
* [Logging](/operations/logging.md)
* [Diagnostic Information](/troubleshooting/diagnostic-information.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/common-issues.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.