null

 

Данная статья вам поможет в решении проблем, возникающих при автоматическом экспорте отчетов.

Эта статья поможет диагностировать и устранять проблемы, которые могут возникнуть при настройке и работе автоматического экспорта отчетов через API (метод automated).

Коды ответов HTTP и их значение

Система использует стандартные HTTP-коды для классификации ошибок:

HTTP-код Название Описание
200 OK Успешное выполнение или проблемы на стороне фронтенда (проверяйте поле success)
400 Bad Request Ошибка валидации входных параметров запроса
403 Forbidden Недостаточно прав для выполнения операции
406 Not Acceptable Ошибка формата данных от клиента (некорректная структура запроса)
500 Internal Server Error Внутренняя ошибка сервера
502 Bad Gateway Ошибка браузера или внешнего сервиса
504 Gateway Timeout Превышено время ожидания ответа

 

Описание ошибок по категориям

Ошибки валидации параметров (HTTP 400)

Возникают при некорректных входных параметрах запроса.

Сообщение об ошибке Причина Решение
Не переданы данные для запуска генерации отчета Пустой массив data в запросе Убедитесь, что массив data содержит хотя бы один элемент
неподдерживаемый тип экспорта: Некорректное значение параметра type Используйте значения: svg или png
неподдерживаемый выходной формат: Некорректное значение параметра output_type Используйте значения: pdf, png, svg или pptx
неподдерживаемый размер страницы: Некорректное значение параметра page_size Используйте значения: A3, A4 или A5
неподдерживаемая ориентация: Некорректное значение параметра page_orientation Используйте значения: portrait или landscape
Некорректный url URL отчета не может быть распознан Проверьте формат URL, он должен содержать идентификатор отчета
Не удалось определить report_id для загрузки PPTX шаблона Для PPTX экспорта не удалось извлечь ID отчета из URL Убедитесь, что URL содержит корректный идентификатор отчета

 

Ошибки прав доступа (HTTP 403)

Возникают при недостаточных правах пользователя.

Сообщение об ошибке Причина Решение
Недостаточно прав для работы от имени другого пользователя Попытка выполнить экспорт от имени другого пользователя без соответствующего права Используйте свой user_id или получите право ImpersonateUser  (право выполнения запроса от имени другого пользователя: надо быть даминистратором)

 

Ошибки формата данных (HTTP 406)

Возникают при некорректной структуре данных от клиента. Сообщения содержат префикс «Ошибка работы с API: неверный вызов».

Сообщение об ошибке Причина Решение
Ошибка работы с API: неверный вызов
Не передан url		 Отсутствует обязательный параметр url в запросе Укажите URL отчета в параметре url
Ошибка работы с API: неверный вызов
Пустые данные export		 Для PPTX экспорта фронтенд вернул пустые данные Проверьте работу отчета в браузере. Для отчета должен быть настроен pptx шаблон
Ошибка работы с API: неверный вызов
Отсутствует поле image		 В данных PPTX от фронтенда отсутствует обязательное поле image Проверьте корректность настройки PPTX экспорта в отчете
Ошибка работы с API: неверный вызов
Отсутствует поле frames		 В данных PPTX от фронтенда отсутствует обязательное поле frames Проверьте корректность настройки PPTX экспорта в отчете

 

Примечание — Ошибки HTTP 406 для PPTX возникают на этапе обработки данных, полученных от браузера. Это означает, что браузер успешно загрузил страницу, но фронтенд вернул некорректные данные для PPTX генерации.

Внутренние ошибки сервера (HTTP 500)

Возникают при проблемах на стороне сервера.

Сообщение об ошибке Причина Решение
Ошибка создания сессии Не удалось создать служебную сессию для пользователя Проверьте, что пользователь существует и не заблокирован
Ошибка загрузки PPTX шаблона Шаблон PPTX не найден или недоступен для данного отчета Убедитесь, что для отчета настроен PPTX шаблон
Ошибка конвертации в PDF Не удалось преобразовать изображение в PDF Проверьте корректность данных изображения от фронтенда
Ошибка создания PPTX Не удалось сгенерировать PPTX презентацию Проверьте корректность данных от фронтенда и наличие шаблона

 

Ошибки браузера (HTTP 502)

Возникают при проблемах с браузером Chrome. Для работы автоэкспорта на сервере должен быть установлен Google Chrome или Chromium.

Сообщение об ошибке Причина Решение
Не удалось открыть URL Chrome не установлен, не найден или не запускается Установите Chrome и укажите путь в конфигурации
Страница не загрузилась (отсутствует body) Страница пустая или возвращает ошибку Проверьте URL отчета в браузере вручную
браузер неожиданно закрылся Не хватает памяти, ошибка Chrome или sandbox Проверьте ресурсы сервера, попробуйте no_sandbox: true
Получены пустые данные Фронтенд не отправил данные экспорта Проверьте работу отчета в браузере, увеличьте delay

 

Частые причины ошибок браузера

  • Chrome не установлен — установите google-chrome-stable или chromium;

  • Chrome не найден — укажите путь в конфигурации (exec_path);

  • Ошибка sandbox — в Docker используйте no_sandbox: true или cap_add: SYS_ADMIN;

  • Missing X server — используйте headless: true на сервере без GUI;
  • Не хватает памяти — Chrome требует минимум 512 МБ RAM на процесс.

Таймауты (HTTP 504)

Возникают при превышении времени ожидания.

Сообщение об ошибке Причина Решение
Таймаут ожидания данных моста Фронтенд не отправил данные в течение указанного времени Увеличьте параметр timeout или оптимизируйте отчет. Проверьте отчет в браузере.

 

Проблемы фронтенда (HTTP 200, success: 0)

Запрос выполнен успешно на уровне HTTP, но фронтенд не смог сгенерировать данные.

Сообщение об ошибке Причина Решение
фронтенд не отправил данные в течение указанного времени Отчет не успел загрузиться за отведенное время Увеличьте параметры delay и timeout Проверьте работу отчета в браузере вручную
ошибка генерации отчета на фронтенде Фронтенд явно сообщил об ошибке Проверьте работу отчета в браузере, убедитесь в доступности данных
некорректные данные от фронтенда Получены поврежденные или неполные данные Проверьте работу отчета в браузере вручную

 

Структура ответов API

Успешный ответ (HTTP 200, success: 1)

{
  "mode": "online",
  "status": 200,
  "message": "",
  "data": [{
    "success": 1,
    "report_id": 123,
    "message": "",
    "elapsed": 15.23,
    "file_data": "base64_encoded_content",
    "file_name": "report_123.pdf",
    "mime_type": "application/pdf",
    "file_size": 12345
  }]
}

Ответ с ошибкой фронтенда (HTTP 200, success: 0)

{
  "mode": "online",
  "status": 200,
  "message": "",
  "data": [{
    "success": 0,
    "report_id": 123,
    "message": "фронтенд не отправил данные в течение указанного времени",
    "elapsed": 125.00
  }]
}

Ответ с ошибкой валидации (HTTP 400)

{
  "mode": "online",
  "status": 400,
  "message": "неподдерживаемый тип экспорта: xlsx (поддерживается: svg, png)\n[call:1234567890]"
}

Ответ с ошибкой формата данных (HTTP 406)

{
  "mode": "online",
  "status": 406,
  "message": "Ошибка работы с API: неверный вызов\nНе передан url\n[call:1234567890]"
}

Ответ с ошибкой выполнения (HTTP 500/502/504)

Ошибки выполнения возникают после успешной валидации параметров — при работе браузера или обработке данных.

{
  "mode": "online",
  "status": 502,
  "message": "Не удалось открыть URL (https://example.com/report/123)\n[call:1234567890]"
}

Ответ с metadata (требуется право Debugging)

Поле metadata с расширенной информацией об ошибке отдаётся только пользователям с правом Debugging (роль DEVELOPER) (см. раздел «Debug режим и диагностика»).

{
  "mode": "online",
  "status": 504,
  "message": "Таймаут ожидания данных моста\n[call:1234567890]",
  "metadata": {
    "report_id": 123,
    "message": "Таймаут ожидания данных моста",
    "elapsed": 125.67
  }
}

Примечание — Metadata содержит: report_id (идентификатор отчета), message (публичное сообщение об ошибке), elapsed (время выполнения в секундах). При включенном debug режиме также добавляется поле debug с логами.

Формат сообщений об ошибках

Сообщения в поле message формируются по следующим правилам:

Тип ошибки HTTP код Формат сообщения
Пользовательская (User) 400 Только текст ошибки
Права доступа (Access) 403 Только текст ошибки
Формат данных (Frontend) 406 «Ошибка работы с API: неверный вызов» + текст ошибки
Внутренняя (Internal) 500 «Внутренняя ошибка сервера» + текст ошибки (если есть)
Внешняя (External) 502 Только текст ошибки
Таймаут (HTTP 504) 504 Только текст ошибки

 

В конце сообщения всегда добавляется идентификатор вызова: [call:XXXXX]

Мониторинг производительности

Нормы времени выполнения

  • 15-45 секунд — норма для обычных отчетов
  • более 90 секунд — проблема, рекомендуется проверить debug логи

Анализ http_stats

Статистика HTTP запросов в debug информации помогает выявить проблемы с данными:

{
  "http_stats": {
    "success_count": 28,
    "error_count": 2,
    "total_count": 30
  }
}
  • Норма: error_count менее 10% от total_count
  • Проблема: error_count более 20% — возможны проблемы с БД или сетью

Разбор типовых проблем

1. Таймаут фронтенда (HTTP 200, success: 0)

{
  "mode": "online",
  "status": 200,
  "message": "",
  "data": [{
    "success": 0,
    "report_id": 123,
    "message": "фронтенд не отправил данные в течение указанного времени",
    "elapsed": 125.123
  }]
}

Причина: Отчет не успел загрузиться за отведенное время.

Решение:

  • Увеличьте параметры delay и timeout
  • Проверьте URL отчета в браузере вручную
  • Включите headless: false для визуальной диагностики

2. Ошибка генерации на фронтенде (HTTP 200, success: 0)

{
  "mode": "online",
  "status": 200,
  "message": "",
  "data": [{
    "success": 0,
    "report_id": 123,
    "message": "ошибка генерации отчета на фронтенде: не удалось загрузить данные виджета",
    "elapsed": 5.23
  }]
}

Причина: Фронтенд явно сообщил об ошибке при генерации.

Решение:

  • Проверьте работу отчета в браузере
  • Убедитесь в доступности данных для виджетов
  • Включите debug: true для анализа http_errors

3. Таймаут ожидания данных (HTTP 504)

{
  "mode": "online",
  "status": 504,
  "message": "Таймаут ожидания данных моста\n[call:1234567890]",
  "metadata": {
    "report_id": 123,
    "message": "Таймаут ожидания данных моста",
    "elapsed": 125.123
  }
}

Причина: Фронтенд не успел подготовить и отправить данные экспорта за отведённое время.

Решение: Увеличьте параметр timeout:

{
  "object": {"name": "exports"},
  "command": {"name": "automated"},
  "data": [{
    "url": "https://server.example.com/report/123",
    "user_id": 1,
    "timeout": 300,
    "delay": 5000
  }]
}

4. Проблемы с Chrome (HTTP 502)

{
  "mode": "online",
  "status": 502,
  "message": "Не удалось открыть URL (https://example.com/report/123)\n[call:1234567890]",
  "metadata": {
    "report_id": 123,
    "message": "Не удалось открыть URL (https://example.com/report/123)",
    "elapsed": 5.67
  }
}

Примечание — Поле metadata отображается только пользователям с правом Debugging.

Частая причина на Ubuntu: snap-заглушка chromium-browser.

Ошибка может содержать:

chrome failed to start:
Command '/usr/bin/chromium-browser' requires the chromium snap to be installed.

Диагностика:

# Проверить что это заглушка
file /usr/bin/chromium-browser

# Проверить установленные браузеры
which google-chrome
which chromium-gost

Решение 1: Удалить заглушку:

sudo apt remove chromium-browser

Решение 2: Явно указать путь к браузеру в конфигурации.

5. Ошибка "Missing X server" (HTTP 502)

{
  "mode": "online",
  "status": 502,
  "message": "Не удалось открыть URL (https://example.com/report/123)\n[call:1234567890]"
}

В логах сервера будет содержаться полная информация:

chrome failed to start:
[ERROR:ui/ozone/platform/x11/ozone_platform_x11.cc:249] Missing X server or $DISPLAY

Причина: Попытка запустить браузер в визуальном режиме (headless=false) на сервере без GUI.

Решение: Используйте headless: true для серверных окружений.

6. Ошибки PPTX генерации (HTTP 500)

{
  "mode": "online",
  "status": 500,
  "message": "Внутренняя ошибка сервера\nОшибка загрузки PPTX шаблона\n[call:1234567890]"
}

Требования для PPTX экспорта:

  1. Шаблон PPTX — должен быть создан и привязан к отчету в настройках
  2. Параметр URL — в URL отчета должен быть ?export=pptx
  3. Настройка отчета — отчет должен поддерживать PPTX экспорт (настраивается в редакторе отчетов)

Частые причины ошибок:

  • Шаблон PPTX не создан или не привязан к отчету
  • URL отчета не содержит параметр ?export=pptx
  • Отчет не настроен для PPTX экспорта

Решение:

  1. В редакторе отчетов создайте PPTX шаблон для отчета
  2. Настройте фреймы (области) для экспорта в шаблоне
  3. Добавьте параметр ?export=pptx в URL запроса

Аварийные процедуры

Chrome завис или не отвечает

# Завершить все Chrome процессы
killall -9 chrome
killall -9 chromium-browser

# Очистка временных файлов Chrome
rm -rf /tmp/.org.chromium.Chromium.*

Проверка ресурсов сервера

# Проверить память
free -h

# Проверить диск
df -h

# Проверить процессы Chrome
ps aux | grep chrome

# Проверить занятые порты (Chrome DevTools)
netstat -tlnp | grep :9222

Чек-лист диагностики

  1. Включить debug режим (debug: true)
  2. Проверить системные ресурсы (free -h, df -h)
  3. Проверить пользователя в системе
  4. Проверить доступность URL отчета (curl URL)
  5. Визуальная диагностика (headless: false) на машине с GUI

Параметры времени ожидания

delay

Базовая задержка на элемент отчета (в миллисекундах).

  • Фронтенд умножает значение на количество элементов отчета
  • По умолчанию: 100 мс
  • Рекомендуемые значения: 100-500 мс в зависимости от сложности отчета

timeout

Максимальное время ожидания ответа (в секундах).

  • По умолчанию: 120 секунд
  • Рекомендуемые значения: 60-300 секунд в зависимости от размера отчета

Рекомендации по устранению проблем

Общие рекомендации

  1. Проверьте URL отчета в браузере вручную
  2. Убедитесь, что все данные отчета загружаются корректно
  3. При таймаутах увеличьте параметры delay и timeout
  4. Для диагностики используйте параметр debug: true (требуется право Debugging)

Настройка браузера

Рекомендуется явно указывать путь к браузеру в конфигурации:

{
  "browser": {
    "exec_path": "/usr/bin/google-chrome-stable",
    "disable_gpu": true,
    "no_sandbox": false
  }
}

Типичные пути к браузеру:

  • Google Chrome (Linux): /usr/bin/google-chrome-stable
  • Chromium ГОСТ (Linux): /usr/bin/chromium-gost
  • Chrome (Windows): C:\Program Files\Google\Chrome\Application\chrome.exe
  • Chrome (macOS): /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

 

Ошибка "Missing X server" при headless=false

Возникает при попытке запустить браузер в визуальном режиме на сервере без GUI.

Решение: Используйте headless: true для серверных окружений. Параметр headless: false предназначен только для локальной отладки на машине с GUI.

Поддерживаемые выходные форматы

Формат output_type Описание
PDF pdf По умолчанию. Конвертирует изображение в PDF с учетом page_size и page_orientation
PNG png Возвращает PNG изображение отчета
SVG svg Возвращает SVG изображение отчета
PPTX pptx Создает PowerPoint презентацию. Требует: созданный PPTX шаблон для отчета

Пример запроса

{
  "object": {"name": "exports"},
  "command": {"name": "automated"},
  "data": [{
    "url": "https://server.example.com/report/123",
    "user_id": 456,
    "output_type": "pdf",
    "page_size": "A4",
    "page_orientation": "landscape",
    "delay": 2000,
    "timeout": 120,
    "headless": true
  }]
}

Чек-лист диагностики

  1. Проверьте корректность URL отчета
  2. Убедитесь, что отчет открывается в браузере вручную
  3. Проверьте права пользователя на доступ к отчету
  4. Убедитесь в достаточности параметров timeout и delay
  5. Проверьте доступность браузера на сервере
  6. При использовании PPTX убедитесь в наличии шаблона
  7. Включите debug режим для получения подробной информации
Связи контента