Files
java-word-pdf/docs/operations/troubleshooting.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

5.2 KiB
Raw Blame History

Troubleshooting

Симптом → причина → действие. Только подтверждённое поведение стендов.

401 «Ключ доступа не передан или неверен»

  • Забыт заголовок X-API-Key / ключ не совпадает со WORDPDF_API_KEY сервера.
  • Prod-like стенд не поднимается без .env — это fail-closed (${WORDPDF_API_KEY:?}), не баг.
  • Запрос идёт через точечный сегмент (/actuator/../api/...) — открытые префиксы с ../%2e ключем не обходятся, так и задумано.
  • Фронт: экран ключа не появляется, хотя сервер его требует? Проверьте, что probeApiKey() дошёл до сервера (network-вкладка); ключ из localStorage стирается при 401.

422 «Конвертация отменена: … найдены диаграммы/SmartArt/OLE-объекты»

Не ошибка — сработал включённый error-флаг запроса. Снимите errorOnCharts/ errorOnSmartArt/errorOnOle (по умолчанию выключены). На .doc флаги не срабатывают в принципе (плейсхолдеры — растры).

503

Очередь конвертации (16 мест) полна: воркер один, все конвертации сериализованы. Повторите позже. Систематически — увеличивайте время ответа вниз (документы поменьше) или масштабируйте количество экземпляров за балансировщиком (каждый со своей очередью).

504

Конвертация дольше wordpdf.convert-timeout (2m). Уменьшите документ (много больших растров/диаграмм) или поднимите таймаут серверу. Учтите: отменённая конвертация дожигается, следующий запрос ждёт её в очереди.

413

Тело больше контейнерного потолка multipart (100 МБ) или nginx client_max_body_size 100m — обе границы стоят 100 МБ. Логический лимит входа (wordpdf.max-mb, дефолт 5 МБ) отсекает раньше и даёт 400, так что 413 — это когда серверный лимит поднят выше 100 МБ бессмысленно либо запрос идёт мимо ожидаемого пути. Файл реально меньше, но 413? Проверьте, не режет ли промежуточный прокси.

В PDF напечатано «...TO HIDE THESE MESSAGES...»

В classpath нет SLF4J-провайдера — docx4j пишет предупреждения прямо в PDF. Для библиотеки: оставить slf4j-simple (в транзитивах wordpdf-core) или принести свой провайдер. Для app: slf4j-simple исключён в пользу logback — если логическая конфигурация app сломана и SLF4J не инициализирован, верните провайдер.

Картинки диаграмм «мыльные» (ресемпл)

Нарушен контракт префикса media-частей /word/media/chart-*: по нему ChartImageHandler отключает пересжатие PNG в FOP. Если части переименованы ручной правкой — верните префикс (DrawingPreRenderer.CHART_MEDIA_URI_PREFIX).

Вместо знаков — # или пустые боксы

  • # — глифа нет ни в шрифте ранa, ни в fallback, и не сработала резка по покрытию (для docx-пута это регрессия — заведите issue с документом).
  • Пустой бокс .notdef для U+2188/U+218A — известное ограничение OFL-бандла, не чинится.
  • «Битый»/подменённый шрифт в целом — проверьте алиасы (Calibri→Carlito и т.д., Шрифты): подмена метрически совместима и ожидаема.

Стенд крутит старый код после пересборки

podman-compose пересобрал образ, но контейнеры остались на старом — перезапустите с --force-recreate (Стенды).

.doc не конвертируется (400)

Проверьте сигнатуру: D0 CF 11 E0 A1 B1 1A E1. Word 6–95 и зашифрованные (Office 95 password) документы мостом не поддерживаются → 400/ValidationException. Расширение .doc при zip-содержимом (переименованный docx) маршрутизируется по байтам — это не ошибка.