Troubleshooting

Типичные симптомы, причина, решение. Ссылки file:line и cross-link к docs.

Запуск и config

Сервер сразу завершается с process.exit(1)

• Причина: провал Zod-валидации env (src/config/env.ts).
• Fix: смотри логи - там указана невалидная переменная. Проверь JWT_SECRET (обяз.), COLLECTOR_SECRET (обяз.), DATABASE_URL, порты. Сравни с .env.example.

COLLECTOR_SECRET mismatch между server и collector

• Симптом: collector не может уведомить о статусе документа; загрузка остаётся "processing".
• Fix: задай тот же COLLECTOR_SECRET в корневом .env (единый config - слой per-package .env удалён в v0.22). Constant-time сравнение → тихая ошибка 401.

WIDGET_API_KEY mismatch widget↔server

• Симптом: виджет не загружает config / chat 401 от сервера.
• Fix: тот же key в корневом .env (единый config). Без key cache-bust push - no-op (TTL 5 min).

Config, изменённый из UI, не действует

• Причина: ключи ALWAYS_READONLY (JWT_SECRET, DATABASE_URL, порты, URL) отклоняются bulk settings; остальные следуют DB > ENV > Default.
• Fix: для readonly-ключей меняй .env + restart. PUT /api/system/settings возвращает { rejected: [...] } - проверь этот массив.

Database

Конфликтующие миграции / dev reset

• Fix: в dev с одноразовой DB reset через pnpm db:migrate:reset:guard (требует PRISMA_MIGRATE_RESET_CONFIRM=yes или --force-accept-data-loss - никогда в продакшене). Deploy с guard: pnpm db:migrate:guard (отклоняет деструктивные миграции без явного согласия). Проверь PostgreSQL 16 и корректный DATABASE_URL.

Restore backup не атомарен / частичные данные

• Причина: restore использует psql --single-transaction --set ON_ERROR_STOP=on; при сбое делает полный rollback.
• Fix: проверь логи psql; safety backup pre-restore (runSafetyBackup). Используй /restore/:logId/dry-run перед реальным restore.

RAG и embedding

Vector search возвращает 0 результатов, но FTS работает

• Причина: guard D-01 - текущий EMBEDDING_MODEL ≠ embeddingModel у Document (например, модель сменена после загрузки): vector leg пропускается, поиск деградирует до FTS-only.
• Fix: re-embed через POST /api/system/reembed-documents (admin, опционально workspaceId/documentIds) для повторного embed chunk'ов текущей моделью; если нужно только перестроить FTS-индекс из vector DB: POST /api/system/reindex-documents. Оба admin-only, также из Settings → Maintenance.

RAG деградирован в виджете (status: rag-degraded)

• Причина: RAG pre-search упал (collector down, пустой whitelist workspace) или 0 результатов поиска по связанным workspace.
• Fix: проверь GET /api/health/rag; проверь WidgetWorkspace для виджета (GET /api/widgets/:id/workspaces); подтверди collector up (GET :3210/api/health).

LanceDB table missing / query error

• Причина: таблица per-workspace ws_<name>_<shortId> не создана или storage перемещён.
• Fix: проверь, что STORAGE_PATH collector не изменён; reindex wiki/документов.

Agent и LLM

Agent abort: unknown_tool_breaker

• Причина: circuit breaker BOT-03 - 3 неизвестных skill подряд / 5 всего. Часто модель галлюцинирует незарегистрированные tool.
• Fix: используй более способную модель или уменьши включённые skill; проверь MCP connection enabled и зарегистрированные skill (mcp_<conn>_<tool>).

Agent abort: wallclock / token_budget / context_overflow

• Fix: подними env AGENT_WALLCLOCK_TIMEOUT_MS (дефолт 600000), AGENT_MAX_TOTAL_TOKENS (200000), AGENT_MAX_CONTEXT_BYTES (500000). Для простых задач понизь, чтобы избежать stall. См. 03 - Configuration § Agent watchdog.

Модель не отвечает / timeout локальной LLM

• Причина: Ollama down или модель не загружена; LLM_TIMEOUT=0 = нет timeout (медленные локальные LLM).
• Fix: ollama list / ollama pull gemma4:latest; проверь OLLAMA_BASE_URL (http://ollama:11434 в compose). Fallback provider: проверь Provider.isAvailable (polling 30s).

Fallback provider не срабатывает

• Причина: нет доступного альтернативного provider (isAvailable=false) или не задан глобальный default.
• Fix: добавь provider (POST /api/providers), set default (PUT /:id/set-default), проверь тег deriveCapabilities. Frontend fallback 3-tier с toast Undo.

Widget

Виджет не загружается / пустой iframe

• Причина: allowedOrigins не содержит origin хоста → динамический CORS fail-closed.
• Fix: добавь origin в Widget.allowedOrigins (CSV-строка, максимум 2000 символов). Проверь, что GET /api/config/:widgetId отвечает.

Lead capture 403

• Причина: config.leadCaptureEnabled=false для этого виджета.
• Fix: включи в модели Widget (admin UI или API).

Rate limit 429 на виджете

• Причина: цепочка limiter - widgetDailyMessageLimiter (5/24h на widget+IP, override sessionLimitPerDay), widgetChatLimiter (30/min на widgetId, override rateLimitPerMinute), widgetSessionLimiter (50 созданий сессий/день на IP), widgetLeadLimiter (3/h на IP).
• Fix: оцени per-widget override (rateLimitPerMinute/sessionLimitPerDay); проверь, какой limiter сработал (header Retry-After / body error).

MCP

Установка из marketplace 201, но tool недоступны

• Причина: connectMCPServer - fire-and-forget; сбой логируется, но не пробрасывается.
• Fix: POST /api/mcp-connections/:id/test (10s, возвращает {success, toolCount, error}). Проверь transport fallback D-09; проверь activeConnections через GET /api/mcp-connections/statuses.

MCP автоматически отключён

• Причина: auto-disable в стиле webhook? Нет - MCP connection остаётся enabled; это webhook само-отключается после 10 последовательных сбоев. Для MCP 30-минутный health check устанавливает healthStatus (stale/down), но не отключает подключение.
• Fix: для webhook включи вручную; для MCP health badge информативен.

Tool MCP не используется в чате

• Причина: активные per-chat pin, исключающие подключение, или connection disabled.
• Fix: GET /api/chats/:chatId/pins; проверь resolveSkillsForChat (нет pin → все enabled подключения workspace).

Лицензия

402 Payment Required на функцию

• Причина: requireFeature(flag) или requireFeatureLimit сработал gating (Community).
• Fix: задай Enterprise LICENSE_KEY или оставайся на Community с лимитами. Body ошибки включает feature, tier, limit?, current?.

Enterprise истёк в runtime

• Поведение: graceful degradation до Community (без restart); warn в логах.
• Fix: обнови LICENSE_KEY; getLicenseInfo() перечитывает в runtime.

Безопасность и audit

Audit log не пишет

• Причина: audit log - модуль Enterprise; в Community logEvent - no-op (write delegate не зарегистрирован), поэтому события не записываются.
• Fix: Enterprise для audit log + immutability (audit_log_immutable). Проверь корректный entityType в фильтрах (GET /api/event-logs). Event-webhook'и в Community всё равно отправляются (fire-and-forget).

DLP не редактирует PII

• Причина: DLP_ENABLED=false через settings (дефолт в v0.22 - "true" - кто-то отключил), или роль в DLP_BYPASS_ROLES, освобождающая от scan.
• Fix: проверь/задай DLP_ENABLED=true через settings. Redaction по 10 встроенным database-backed паттернам: 6 оригинальных (email, credit_card, ssn, api_key, aws_key, private_key) плюс 4 EU/IT (it_vat_iva, it_codice_fiscale, iban, eu_phone - последний seeds DISABLED для admin review); кастомные паттерны до 50 через панель DLP Patterns. SSE done → dlp_matches (frontend показывает DLPNotice под сообщением).

Backup

Job backup вечно в "running"

• Причина: worker умер без cleanup; DB mutex BackupLog.status="running".
• Fix: cleanStaleLocks помечает running >2h как failed при следующем bootstrap. Перезапусти сервер для триггера или обнови status вручную.

Checksum mismatch при restore

• Причина: повреждённый архив / частичная загрузка.
• Fix: SHA-256 streaming вычисляется при загрузке; проверь файл назначения. Восстанови из следующего log.

Известные расхождения документации

Быстрый health check

curl localhost:3000/api/health        # { database, collector, disk }
curl localhost:3000/api/health/rag    # статус RAG
curl localhost:3210/api/health        # collector
curl localhost:3211/health            # widget

Cross-link

• Config/env: 03 - Configuration
• Internals: 05 - Feature Guide
• Deploy: 09 - Deployment