Перейти к основному содержимому

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

Типичные проблемы при работе с 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-поддержку

Ошибка: Сертификат не прошёл проверку​

Симптом:

curl: (60) SSL certificate problem: self-signed certificate in certificate chain

При установке пакета ошибка выглядит так:

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

Причина: Сеть заменяет сертификат сайта своим. Так работают корпоративные прокси, VPN и антивирусы с проверкой трафика.

Решение:

  1. Проверьте, кто выдал сертификат. Подойдёт любой из способов:

    • Браузер на любой ОС. Откройте pypi.org, нажмите значок слева от адреса и откройте сведения о сертификате. Издатель указан в поле «Кем выдан» (Issued By).

    • Терминал на macOS, Linux или в WSL:

      openssl s_client -connect pypi.org:443 -servername pypi.org </dev/null 2>/dev/null | openssl x509 -noout -issuer

    • PowerShell на Windows:

      $tcp = New-Object Net.Sockets.TcpClient('pypi.org', 443)
      $callback = { $true } -as [Net.Security.RemoteCertificateValidationCallback]
      $tls = New-Object Net.Security.SslStream($tcp.GetStream(), $false, $callback)
      $tls.AuthenticateAsClient('pypi.org', $null, [Security.Authentication.SslProtocols]::Tls12, $false)
      $tls.RemoteCertificate.Issuer
      $tcp.Close()

    Если издатель - ваша компания или средство защиты, сертификат подменяет ваша сеть. Если издатель незнаком, остановите установку и обратитесь к администратору сети.

    Браузер и терминал могут работать через разные прокси. Если браузер показывает публичного издателя, а ошибка в терминале остаётся, проверьте издателя командой.

  2. Получите в IT-поддержке корневой сертификат компании в формате PEM.

  3. Установите CLI без установочного скрипта и укажите путь к файлу сертификата:

    python3 -m venv ~/.trisigma-cli
    ~/.trisigma-cli/bin/pip install --cert /path/to/company-ca.pem --index-url https://pypi.org/simple/ trisigma-cli
    echo 'export PATH="$HOME/.trisigma-cli/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    trisigma --version

    Для bash замените ~/.zshrc на ~/.bashrc. На Windows CLI работает через WSL, поэтому выполняйте эти команды в WSL.

Не отключайте проверку сертификатов

Флаги -k, --insecure и --trusted-host отключают проверку подлинности источника. В этом режиме на компьютер попадает код, происхождение которого не подтверждено.

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

Симптом:

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:&lt;your-company&gt;/&lt;your-company&gt;_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://&lt;your-company&gt;-conf.trisigma.io/oauth/authorize?...

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

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

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

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

Симптом:

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

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

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

    curl -s -o /dev/null -w "%{http_code}" https://&lt;your-company&gt;-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:

    1. macOS: brew install git
    2. Linux: sudo apt-get install git

  2. Проверь что ты в 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.

  2. Если ничего не вывелось. настрой 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. Используй современный терминал:

    1. macOS: iTerm2
    2. Linux: GNOME Terminal, Konsole

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

    echo $LANG

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

  3. Установи кодировку (если нужно):

    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://&lt;your-company&gt;-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

Уровни логирования:

  1. ERROR. только ошибки (по умолчанию)
  2. WARNING. предупреждения и ошибки
  3. INFO. информационные сообщения
  4. DEBUG. подробная отладочная информация

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

trisigma sl validate > output.log 2>&1

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

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

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

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

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

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

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