Решение проблем

Распространённые проблемы при работе с можно. и способы их решения.

SDK

SDK не подключается к серверу

Симптом: клиент не стартует, start() выбрасывает исключение или Promise отклонён.

Причины и решения:

Причина	Решение
Неверный URL сервера	Проверьте mozhnoUrl / url. Должен быть полный URL с протоколом.
Неверный API-ключ	Проверьте apiKey. Ключ показан только один раз при создании — создайте новый, если утерян.
Сервер недоступен	curl http://localhost:8080/actuator/health. Если нет ответа — сервер не запущен.
Несовпадение окружения	API-ключ привязан к окружению. Ключ от dev не даст доступ к production.
Сетевые ограничения	Проверьте firewall, VPN, прокси.

Флаг всегда возвращает false

Причины:

Причина	Решение
Флаг в архиве	Восстановите флаг: POST /api/v1/flags/{id}/unarchive
Стратегия выключена	Проверьте в веб-панели: enabled: true
Контекст не совпадает	Проверьте атрибуты контекста и правила таргетинга
Флаг не существует	Проверьте ключ на опечатки. isEnabled возвращает false для неизвестных флагов.
Кеш устарел	Подождите polling-интервал (15 сек) или перезапустите SDK

Флаги не обновляются после изменения в панели

Причина: polling-интервал.

Решение:

• По умолчанию SDK опрашивает сервер каждые 15 секунд
• Дождитесь следующего цикла поллинга
• Уменьшите fetchTogglesInterval / refreshInterval (но не ниже 5 секунд)
• Для мгновенного применения используйте Kill Switch

SDK выбрасывает исключение при старте

В Java SDK при synchronousFetchOnInitialisation(true):

// При недоступном сервере выбросит исключение
MozhnoConfig config = MozhnoConfig.builder()
    .synchronousFetchOnInitialisation(true)  // <-- вот причина
    .build();

Решение: оберните в try/catch или отключите синхронную загрузку (SDK продолжит фоновые ретраи).

Аутентификация

«401 UNAUTHORIZED» на все запросы

Причина	Решение
JWT истёк (15 мин)	Обновите токен через POST /api/v1/auth/refresh
Refresh-токен истёк (30 дней)	Перелогиньтесь
TOKEN_REUSE	Ваш refresh-токен был использован повторно (возможная компрометация). Перелогиньтесь.
Неверный формат заголовка	Должно быть Authorization: Bearer <token>

«403 FORBIDDEN»

Роль	Доступ
VIEWER	Только чтение. Нельзя создавать/изменять флаги.
DEVELOPER	Нельзя управлять пользователями и API-ключами.

Запросите повышение роли у ADMIN.

База данных

Сервер не стартует: «Connection refused»

Причина: PostgreSQL недоступна.

Решение:

1. Проверьте SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, SPRING_DATASOURCE_PASSWORD
2. Убедитесь, что PostgreSQL запущен: pg_isready -U flags_user -d feature_flags
3. В Docker: проверьте depends_on: postgres: service_healthy

Миграции Flyway не применяются

Симптом: ошибки liquibase или таблицы не созданы.

Решение:

1. Проверьте SPRING_FLYWAY_ENABLED=true
2. Проверьте SPRING_FLYWAY_LOCATIONS=classpath:db/migration
3. Посмотрите таблицу flyway_schema_history в БД — есть ли в ней записи

Метрики

Метрики не отображаются в панели

Причина	Решение
disableMetrics: true в SDK	Уберите или поставьте false
Интервал ещё не прошёл	Метрики отправляются раз в 60 секунд
CLIENT_MAX_METRICS_PER_KEY превышен	Увеличьте лимит или удалите старые метрики

Sparkline-график пустой

Метрики накапливаются со временем. Дайте SDK поработать хотя бы 5–10 минут, чтобы появились данные.

Rate Limiting

«429 RATE_LIMIT_EXCEEDED»

Вы превысили лимит запросов. Лимиты:

Операция	Лимит
Логин	5 попыток в минуту
Сброс пароля / приглашение	3 попытки в час
Refresh токен	10 попыток в минуту
SDK-запросы	1000 в минуту
Admin write-операции	100 в минуту

Решение: дождитесь следующего интервала пополнения или увеличьте лимиты через переменные окружения.

Деплой

Docker-контейнер перезапускается

Причины:

1. База данных не готова — увеличьте start_period в healthcheck
2. Переменная JWT_SECRET не задана в проде
3. Недостаточно памяти — проверьте docker stats, увеличьте deploy.resources.limits.memory

502 / 504 за обратным прокси

Увеличьте таймауты прокси:

proxy_read_timeout 60s;
proxy_connect_timeout 10s;

Что дальше?

• Мониторинг — health checks, метрики, логи
• Конфигурация — все переменные окружения
• SDK: Обзор — архитектура клиентских библиотек