# Подводные камни

Список реальных проблем exteraGram/Chaquopy и их решений. Большинство обнаружено эмпирически на устройстве — здесь собрано всё.

## Экран несовместимости «Твой плагин требует >=X»

**Симптом:** при установке exteraGram показывает экран про требуемую версию приложения, даже если версия подходит.

**Причина:** нестандартный дандер `__min_version__`.

**Решение:** catalib эмитит только канонический `__app_version__` и **никогда** `__min_version__`. Если вы пишете дандеры вручную (без catalib) — не используйте `__min_version__`.

## `Plugin requires sdk version >=X, but current is Y`

**Симптом:** установка блокируется из-за версии SDK.

**Причина:** `sdk_version` в манифесте выше, чем SDK на устройстве (встречались `1.4.3.3` и `1.4.4.1`).

**Решение:** не задавайте `sdk_version`, если плагин не требует конкретной новой возможности SDK. Это поле — жёсткий гейт.

## `TypeError: MenuItemData.__init__() got an unexpected keyword argument 'item_type'`

**Причина:** неверный аргумент при создании пункта меню.

**Решение:** реальный API — `MenuItemData(menu_type=MenuItemType.X, text=..., on_click=...)`, обработчик принимает `context: dict`. В catalib используйте декоратор `menu_item(text, menu_type="DRAWER_MENU", ...)` — он строит корректный `MenuItemData` сам. Метод-обработчик **обязан** принимать `context`.

## `menu_item() got an unexpected keyword argument 'menu_type'` / падение старым кодом

**Причина:** в общий `sys.modules` интерпретатора попала вендоренная копия `catalib.support` из **прошлого деплоя**, и Python берёт её из кеша мимо нашего finder'а. Свежий бандл исполняется старым кодом.

**Решение:** встроенный загрузчик при каждой загрузке вычищает устаревшие вендоренные `catalib.*` (по пометке или синтетическому origin). Достаточно установить бандл, собранный актуальной версией catalib — он сам почистит кеш. Если зависли в неопределённом состоянии — перезапустите exteraGram.

## Нативный креш при `platform.platform()` / `subprocess`

**Причина:** в Chaquopy недоступны `fork/exec`; `subprocess`, `os.fork`, `platform.platform()` роняют процесс (SIGSYS).

**Решение:** не порождайте процессы. Для идентификации среды — `os.uname()`, `sys.platform`, `sys.version`.

## Плагин не включается из кода

**Симптом:** после деплоя `enabled: false`, `set_plugin_enabled` не помогает.

**Причина:** на части сборок dev server применяет `set_plugin_enabled` только при открытом экране плагинов в UI.

**Решение:** включите плагин один раз вручную в настройках плагинов exteraGram. Признак успешной загрузки — `error: null` в `get_plugins` (а не `enabled`).

## `delete_plugin` не удаляет файл

**Причина:** особенность части сборок dev server; приватный каталог без root недоступен для `adb`.

**Решение:** удаляйте плагин через UI exteraGram.

## Логи плагина не видны в `adb logcat`

**Причина:** в некоторых сборках вывод `log()`/stdout не доходит до logcat.

**Решение:** для диагностики пишите данные в файл в каталоге плагина и забирайте его; используйте `error: null` как индикатор успешной загрузки.

## Метаданные не считываются (плагин «без имени»)

**Причина:** динамические метаданные (`__id__ = NAME`, `__id__ = f"..."`, конкатенация) — exteraGram читает только строковые литералы.

**Решение:** задавайте метаданные в `catalib.toml`. catalib эмитит их литералами и статически отклоняет динамические (это видно ещё на сборке).

## `DiscoveryError: каталоги с модулями без __init__.py`

**Причина:** каталог в `src` содержит модули, но не является пакетом.

**Решение:** добавьте `__init__.py` в каждый каталог с модулями.

## Имя файла должно совпадать с `__id__`

exteraGram импортирует плагин как модуль `<plugin_id>`. catalib сам называет выходной файл `<plugin_id>.py`/`.plugin` и проверяет совпадение `__id__` с именем файла — следите лишь за корректным `id` в манифесте (`^[a-z][a-z0-9_]{1,31}$`, без дефисов).

## `RequirementsError: бинарный пакет ...`

**Причина:** зависимость с бинарными расширениями (`numpy`, `pandas`, `cryptography`, `opencv-*` и т. п.).

**Решение:** только pure-Python пакеты. См. [Зависимости](/catalib/rukovodstvo/dependencies.md).

## `DevServerError: не удалось подключиться`

**Причина:** exteraGram не запущен или не включён режим разработчика.

**Решение:** запустите приложение, включите движок плагинов и режим разработчика; проверьте `adb devices`. См. [Подготовка устройства](/catalib/deploi/device-setup.md).

## Относительные импорты «ломаются» вне catalib

Если копировать собранный код кусками — относительные импорты не сработают. Запускайте плагин только как цельный собранный файл (его загрузчик и настраивает пакетную структуру). Для отладки логики — офлайн-тесты доменных слоёв.

## `ModuleNotFoundError: catalib.support.<area>` в собранном плагине

**Причина:** при `vendor = "auto"` (по умолчанию) в файл вшиваются только модули `catalib`, которые видны статическим анализом импортов. Если плагин обращается к подмодулю `catalib` **динамически** (через `importlib.import_module`, `__import__`, строку), анализатор его не видит и модуль отсекается.

**Решение:** задайте в манифесте

```toml
[build]
vendor = "full"
```

либо импортируйте нужное явно (`from catalib.support import <area>`) — тогда `auto` его сохранит. Неоднозначные импорты (весь пакет как объект, `import *`) catalib и так трактует консервативно — вендоринг полный с предупреждением в выводе `catalib build`. См. [манифест](/catalib/rukovodstvo/manifest.md) и ADR-0008.

## Эталон

Все перечисленные классы ошибок отражены в офлайн-тестах catalib и/или в его поведении. Если встретили новый случай — проверьте `error` плагина через `get_plugins` и сверьтесь с разделом [Как работает сборка](/catalib/vnutrennee-ustroistvo/how-it-works.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://raito-kyokai.gitbook.io/catalib/reshenie-problem/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.