# Troubleshooting

Этот документ помогает быстро проверить типовые проблемы при запуске и работе Crank.

## Веб-интерфейс открывается, но данные не загружаются

Проверьте `admin-api`:

```bash
curl http://127.0.0.1:3001/health
docker compose logs -f admin-api
```

Типовые причины:

- `admin-api` не подключился к PostgreSQL;
- неверные `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`;
- reverse proxy не проксирует `/api/admin/`;
- браузерная сессия истекла.

## `502 Bad Gateway` через nginx

Проверьте, на каком адресе опубликованы контейнеры:

```bash
docker compose ps
```

Если nginx работает на другом host, в `.env` нужно:

```env
CRANK_PUBLISH_BIND=0.0.0.0
```

Если nginx работает на том же host, обычно достаточно:

```env
CRANK_PUBLISH_BIND=127.0.0.1
```

## MCP-клиент получает `401 Unauthorized`

Проверьте:

- API-ключ создан именно для нужного агента;
- ключ передается как `Authorization: Bearer <key>`;
- ключ не был удален или отозван;
- MCP URL содержит правильные `workspace_slug` и `agent_slug`.

## MCP-клиент не видит инструмент

Проверьте:

- операция опубликована;
- операция привязана к агенту;
- агент опубликован;
- ключ выдан на этого агента;
- прошел интервал `CRANK_MCP_REFRESH_MS`.

Для demo seed ожидаемый инструмент:

```text
frankfurter_latest_rate
```

## Тест операции возвращает ошибку внешнего API

Откройте preview запроса в wizard-е и проверьте:

- `base_url`;
- `path_template`;
- HTTP method;
- query/path/body mapping;
- auth profile;
- статические заголовки.

Для Frankfurter рабочий запрос:

```text
GET https://api.frankfurter.dev/v1/latest?base=USD&symbols=EUR
```

## Секрет не виден после создания

Это ожидаемое поведение. Crank шифрует секрет и больше не возвращает его значение через UI или API.

Если значение нужно заменить, используйте **Ротировать**.

## После обновления не появился demo-пример

Проверьте:

```env
CRANK_DEMO_SEED=true
```

Затем перезапустите `admin-api`:

```bash
docker compose up -d admin-api
```

Seed идемпотентный: он не создает дубликаты, но поддерживает Frankfurter-пример.

## Контейнеры не стартуют из-за занятых портов

Проверьте, кто занимает порт:

```bash
docker ps --format 'table {{.Names}}\t{{.Ports}}'
sudo ss -ltnp
```

Чаще всего конфликтуют:

- `3000` - UI;
- `3001` - Admin API;
- `3002` - MCP server;
- `5432` - PostgreSQL, если включен profile `local-db`.

## PostgreSQL недоступен

Проверьте доступность из контейнера:

```bash
docker compose exec admin-api sh -lc 'nc -vz "$POSTGRES_HOST" "$POSTGRES_PORT"'
```

Проверьте переменные:

```bash
docker compose exec admin-api env | grep POSTGRES
```

## Где смотреть логи

```bash
docker compose logs -f admin-api
docker compose logs -f mcp-server
docker compose logs -f ui
```

Для подробных логов временно укажите:

```env
CRANK_LOG_LEVEL=debug
```