# Troubleshooting

Диагностика типовых проблем 1C MCP Gateway: connection, MCP, index, policy.

## Prerequisites

- Доступ к логам процесса gateway (stderr) и `.data/` (`ONEC_MCP_DATA_DIR`).
- Версии: Node 22+, platform 1C, путь к repo `/var/www/mwi.yatsuk.pro`.
- Для HTTP: curl, jq, valid MCP token.

## Пошаговая диагностика

### 1. Gateway не стартует

```bash
cd /var/www/mwi.yatsuk.pro
npm run typecheck
node -v   # expect 22+
npm run dev:gateway 2>&1 | tee /tmp/gateway.log
```

| Симптом | Fix |
|---------|-----|
| `EADDRINUSE :3000` | `ONEC_MCP_HTTP_PORT=3001` или kill stale process |
| `ENOENT tsx` | `npm ci` |
| Permission `.data` | `chmod` / `ONEC_MCP_DATA_DIR` writable |

### 2. MCP client disconnected (stdio)

- Проверьте **абсолютный** `cwd` в mcp.json.
- `npm` в PATH IDE (macOS GUI apps — minimal PATH).
- Альтернатива: `"command": "/usr/bin/node", "args": ["dist/apps/gateway/src/server.js"]` после `npm run build`.

### 3. HTTP MCP 401/403

```bash
curl -v -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-MCP-Client-ID: cursor" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```

- 401: token hash mismatch, expired, revoked
- 403: `allowedClients` не содержит client id
- Bootstrap: `ONEC_MCP_HTTP_TOKEN` only on first start

### 4. Connection / health failures

```bash
# tool: check_connection_health { "profileId": "..." }
# OData:
curl -sS -u user:pass "https://host/base/odata/standard.odata/\$metadata" | head
# HTTP service:
curl -sS "https://host/base/hs/mcp-gateway/health"
```

| Error | Fix |
|-------|-----|
| HTTPS required | HTTPS URL or `ONEC_MCP_ALLOW_INSECURE_HTTP=1` (dev) |
| OData 404 | Publish standard.odata, fix `odataPath` |
| Timeout | Network, 1C cluster load, firewall |

### 5. BSL index empty / stale

- Verify `edtExportPath` / `gitPath` exists and readable.
- Delete profile index cache in `.data` (backup first — [PRODUCTION_STORAGE.md](./PRODUCTION_STORAGE.md)).
- Re-trigger: `discover_1c_context` or restart gateway.

### 6. Policy / approval errors

- Write tool → need `approval.create` first ([MCP_CONNECTION.md](./MCP_CONNECTION.md)).
- `production` → write tools hidden in `tools/list`.
- Approval `used` → create new approval.

### 7. Storage / migration

```bash
curl -s http://localhost:3000/api/system/storage-meta
curl -s -X POST http://localhost:3000/api/system/backups
```

Failed migration — restore backup, check `store-meta.json` version.

## Copy-ready debug env

```bash
export ONEC_MCP_DATA_DIR=/tmp/onec-mcp-debug
export ONEC_MCP_ACTOR=debug
export ONEC_MCP_ALLOW_INSECURE_HTTP=1
rm -rf "$ONEC_MCP_DATA_DIR" && mkdir -p "$ONEC_MCP_DATA_DIR"
npm run dev:gateway
```

Isolated data dir для repro без prod state.

## Проверка tools/list

Baseline smoke:

```
list_profiles → get_active_profile → check_profile_health
```

If fails — problem is gateway/policy, not 1C content.

## Первый тестовый prompt (support)

```
Выполни диагностическую последовательность: list_profiles, для каждого профиля check_profile_health,
верни таблицу profileId / type / environment / health.ok. Без секретов и без raw OData rows.
```

## Типовые ошибки (quick reference)

| Code/Message | Doc |
|--------------|-----|
| OData metadata failed | [ONEC_ODATA_SETUP.md](./ONEC_ODATA_SETUP.md) |
| httpServicePath required | [ONEC_HTTP_SERVICE_SETUP.md](./ONEC_HTTP_SERVICE_SETUP.md) |
| executable not in allowlist | [EDT_DESIGNER_EXPORT.md](./EDT_DESIGNER_EXPORT.md) |
| Approval required | [MCP_CONNECTION.md](./MCP_CONNECTION.md) |
| Token 429 | [BILLING_AND_LIMITS.md](./BILLING_AND_LIMITS.md) |

## Security warning

- Debug logs may leak URLs — disable verbose logging in prod.
- Do not attach `.data/` or audit.jsonl to public tickets without redaction.
- `ONEC_MCP_ALLOW_INSECURE_HTTP=1` only on isolated dev hosts.

## Related docs

- [QUICK_START.md](./QUICK_START.md)
- [RUNBOOK.md](./RUNBOOK.md) — production incidents
- [DEPLOYMENT.md](./DEPLOYMENT.md)
- [THREAT_MODEL.md](./THREAT_MODEL.md)