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

Каталог типовых проблем и решений. Если что-то не описано — ~/.astracode/log/astracode-tui.log часто содержит подсказку.

Установка и запуск

astracode: command not found

Бинарь не в PATH.

which astracode               # должно вывести путь
ls -la /usr/local/bin/astracode

Если файла нет — переустановите (02-installation.md).

Если файл есть, но не находится — проверьте $PATH:

echo $PATH

/usr/local/bin должен быть там. Иначе:

export PATH="/usr/local/bin:$PATH"

TUI запускается, но «висит» на старте

Чаще всего — MCP-сервер с required = true не отвечает.

tail -50 ~/.astracode/log/astracode-tui.log

Ищите mcp:: строки. Если сервер падает — отключите его в config:

[mcp_servers.problematic]
enabled = false

Или, если временно, запустите без mcp:

astracode -c 'mcp_servers={}'

Could not find suitable model provider

Провайдер не настроен.

В TUI:

/model

→ выбрать или добавить.

Если TUI не открывается до конфигурации — задайте ключ провайдера через CLI (команда читает ключ из стандартного ввода):

echo "sk-..." | astracode provider-secret set openai

TUI запускается, но цвета сломаны

Проверьте, что терминал поддерживает 256 цветов:

echo $TERM
# должно быть xterm-256color или похожее

Установить:

export TERM=xterm-256color

Или в ~/.bashrc / ~/.zshrc.

Sandbox / bwrap (Linux)

bwrap: setting up uid map: Permission denied

Linux запретил unprivileged user namespaces.

sudo sysctl kernel.unprivileged_userns_clone=1

Или, чтобы постоянно:

echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/00-userns.conf
sudo sysctl -p

В ограниченных контейнерах (Docker без --privileged), где песочница недоступна, запускайте AstraCode с менее строгим режимом песочницы (оправдано, только если сам контейнер уже изолирован):

sandbox_mode = "danger-full-access"

Подробнее про режимы — 13-safety.md.

bwrap: No such file or directory

System bwrap не установлен. AstraCode использует встроенный (если есть).

Лучше установить:

sudo apt install bubblewrap     # Debian/Ubuntu
sudo dnf install bubblewrap     # Fedora

Sandbox блокирует нужную операцию

Например, нужно прочитать /opt/proprietary-data/.

/sandbox-add-read-dir /opt/proprietary-data

(Только на сессию. Для постоянного — [sandbox_workspace_write].writable_roots в config.)

Секреты

Failed to decrypt secrets file

Master-ключ из OS keyring разъехался с зашифрованным файлом. Не баг версии, не проблема обновления.

Лечение (если у вас немного API-ключей и не жалко переввести):

rm ~/.astracode/secrets/local.age
astracode
# /model → ввести ключи заново

Если ключей много — единственный способ восстановить: - Вспомнить, в каком keyring они лежали. - Восстановить (восстановить пароль, импортировать backup keyring).

Бэкап секретов без master-ключа из keyring невозможен. Это особенность дизайна — для безопасности.

OS keyring недоступен (headless server)

AstraCode упадёт с предложением fallback'а в файл ~/.astracode/secrets/local.key.

Это безопаснее, чем plaintext, но менее безопасно, чем keyring.

Если у вас headless Linux без D-Bus:

# поставить и запустить keyring демона
sudo apt install gnome-keyring
eval $(gnome-keyring-daemon --start)

Или использовать fallback (он включится автоматически, если keyring не отвечает).

Модели и провайдеры

401 Unauthorized при запросе к модели

API-ключ протух или неверный.

/model

→ выбрать провайдера → d (удалить) → + Add provider (заново).

Или проверьте baseURL — иногда у API endpoint меняется адрес.

429 Rate limit exceeded

Провайдер ограничивает запросы. Что делать: - Подождать (AstraCode сам ретраит с backoff). - Поднять тариф у провайдера. - Сменить модель на другую (/model → менее загруженная).

Connection refused / Timeout

Сеть до провайдера не доходит.

Проверьте:

curl -v https://api.openai.com/v1/models  # должно вернуть 401 или JSON

Если нужен прокси:

[network]
http_proxy = "http://proxy.company.com:3128"
https_proxy = "http://proxy.company.com:3128"

Self-signed certificate ошибка

При on-prem с собственным CA:

export ASTRACODE_CA_CERTIFICATE=/etc/ssl/certs/company-ca.pem
astracode

Стриминг не работает

Если ответ модели приходит весь сразу (не по словам) — провайдер не поддерживает SSE. Это нормально для некоторых local LLM. AstraCode переключится на blocking mode автоматически.

Если хочется streaming — проверьте флаги вашего vLLM / llama.cpp.

Сессии и rollout

/resume не показывает старые сессии

Возможно: - state_5.sqlite corrupted. Проверьте: bash sqlite3 ~/.astracode/state_5.sqlite "SELECT COUNT(*) FROM threads;" - Фоновый backfill ещё не закончился. Подождите 1-2 минуты.

Если БД сломана:

mv ~/.astracode/state_5.sqlite ~/.astracode/state_5.sqlite.broken
astracode    # создаст новую, backfill пройдёт по rollout-файлам

/resume <id> — No saved chat found

ID неточный или сессия удалена.

Без аргумента:

/resume

Откроется picker — выберите вручную.

Rollout-файл не пишется

Проверьте права:

ls -la ~/.astracode/sessions/

Должны быть RW для вас.

Slash-команды

/locale ru ничего не делает

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

/new
/locale ru

/cd <path> — directory not found

Tab автодополнение покажет валидные пути. Используйте абсолютный путь, если относительный не работает.

Файл не находится, хотя путь выглядит правильно

Скорее всего в имени есть невидимый Unicode-символ — неразрывный пробел (NBSP, U+00A0), нулевой пробел (zero-width space, U+200B), узкий неразрывный пробел (U+202F) и т. п. Они визуально неотличимы от обычного пробела, но модель при формировании вызова инструмента (rm, cat, read_file) нормализует их в обычный пробел U+0020, и файл «по похожему имени» не находится → ошибка ENOENT.

Как поймать такие имена вручную:

ls "<подозрительная папка>" | cat -A     # NBSP выглядит как M-BM-
LC_ALL=C grep -aP '\xc2\xa0' <(ls)        # найти строки с NBSP

Откуда они берутся: чаще всего файлы, скопированные с macOS — там русская раскладка вставляет NBSP по ⌥ Option+Space, а автокоррекция в Notes/Pages подменяет обычные пробелы на NBSP. Finder при Cmd+D копирует имя как есть.

/review зависает

Большой diff (>5000 строк) — модель долго думает. Подождите, или прерывайте (Esc) и:

/review only the changes in src/

С фокусом на меньший scope.

/goal не сохраняется

sqlite3 ~/.astracode/state_5.sqlite "SELECT * FROM thread_goals;"

Если БД сломана — см. выше (восстановление state_5.sqlite).

Производительность

TUI медленно реагирует

• Большая история — /compact или /new.
• Включены все скиллы — отключите ненужные через /skills.
• Локальная LLM медленная — переключитесь на cloud (/model).

Высокая загрузка CPU

• Анимации — [tui].animations = false.
• Memory Phase 2 в фоне — это нормально, проходит сама.
• Если постоянно — RUST_LOG=debug astracode 2> /tmp/log покажет, где затык.

Большой расход токенов

• Длинная история — /compact.
• Много активных скиллов — /skills → выключить лишние.
• Многие MCP-серверы — то же.
• Reasoning на high — снизить до medium: toml model_reasoning_effort = "medium"

Approval-диалоги

Каждое действие спрашивает разрешение

У вас approval_policy = untrusted. Сменить:

/approvals

→ выбрать пресет «Default» (рекомендуется) или «Full Access».

Или в config (значение по умолчанию — on-request):

approval_policy = "on-request"

Approval-диалог не появляется, тулз не выполняется

Возможно, hook блокирует. Проверьте:

grep -i hook ~/.astracode/log/astracode-tui.log

Или временно отключите хуки:

hooks = {}

Авто-проверка отклонила нужное действие

Если включён режим авто-проверки (/approvals → «Авто-проверка»), подтверждения обрабатывает сабагент-страж, и он мог ошибочно отклонить действие. Чтобы разрешить повтор:

/autoreview

Откроется список последних отклонённых действий с обоснованием. Выберите нужное — AstraCode разрешит один его повтор. Учтите: повтор всё равно снова пройдёт авто-проверку, а сам режим можно вернуть к ручным подтверждениям через /approvals.

Память

Агент не запоминает то, что я ему говорю в диалоге

Это ожидаемое поведение, а не баг. Агент не пишет память «на лету» — у него нет такого инструмента, и системная инструкция запрещает ему менять память (только читать). На фразу «запомни X» он ответит согласием, но ничего не запишет. Память наполняет отдельный фоновый процесс по прошлым сессиям. Подробнее — 12-memory.md.

Память не «помнит» меня после перезапуска

Проверьте, что функция вообще включена:

/memories

1. Функция памяти — экспериментальная и по умолчанию выключена. В TUI /memories предложит её включить; в IDE-плагине нужно прописать [features] memories = true в config.toml.
2. Должны быть включены оба переключателя: Use memories и Generate memories.
3. После включения нужен перезапуск AstraCode.

Кроме того, сессия должна «отлежаться» — этап извлечения запускается не раньше чем через 6 часов простоя (по умолчанию) и при следующем запуске AstraCode. Если работаете без пауз — память не успевает извлечься.

MEMORY.md пустой

Этап консолидации ещё не отрабатывал — он запускается периодически или при накоплении. Подождите следующих запусков.

Память «загрязнилась» случайным фактом

Правьте файл вручную — агент не может удалить запись по просьбе:

nano ~/.astracode/memories/<file>.md

Удалите неправильный фрагмент и сохраните. Полностью очистить — «Сбросить всю память» (Reset all memories) через /memories.

MCP

MCP-сервер не запускается

/mcp verbose

Покажет статус и последнюю ошибку. Логи:

grep mcp:: ~/.astracode/log/astracode-tui.log

Типовое: - Сервер не установлен: command not found. Поставьте (npm install, pip install, ...). - Переменная окружения отсутствует: проверьте env_vars = [...]. - Таймаут: увеличьте startup_timeout_sec = 30.

MCP-tools не появляются у модели

Проверьте:

/mcp

Если сервер «not authenticated» — выполните вход через CLI: astracode mcp login <server> (а astracode mcp logout <server> — выход). В TUI команда /mcp принимает только verbose и лишь показывает статус.

Если enabled = false — поставьте true в config.

После правки — перезапустите AstraCode.

Локализация

Интерфейс на английском, хочу русский

/locale ru

(Если не сработало — см. выше «only before first message».)

Или в config:

[tui]
locale = "ru"

И перезапуск.

Часть текстов на английском, часть на русском

Это норма — переведено не всё (например, имена slash-команд /cd, /help). Ответы модели — на языке, на котором вы пишете.

Прочие странности

TUI «исчез» после Ctrl-Z

Вы случайно нажали Ctrl-Z (SIGTSTP) — AstraCode приостановился.

fg

Вернёт его. Или просто bg чтобы оставил в фоне (но тогда не управляется).

Чтобы Ctrl-Z вообще не работал в AstraCode — добавьте hook или перебиндите в /keymap.

Терминал «сломался» после выхода из AstraCode

Особенно если выход был не «чистый» (Ctrl-Z, kill). Восстановить:

reset
# или
stty sane

Иногда помогает:

tput reset

Файлы в проекте изменились, а я не помню

git status
git diff

Откатить, если не нужно:

git checkout -- <file>

В будущем — approval_policy = "untrusted" для проектов, где не хотите изменений без явного согласия.

Сбор логов для bug-report'а

Если ничего не помогает:

# Самые свежие логи
tail -200 ~/.astracode/log/astracode-tui.log > /tmp/astracode-debug.txt

# Конфиг (без секретов): в TUI введите /debug-config и скопируйте вывод.
# (Команды `astracode debug-config` в CLI нет — это slash-команда внутри TUI.)

# Версия
astracode --version >> /tmp/astracode-debug.txt

Отправляйте через /feedback (категория Bug) — приложит метаданные автоматически. Не отправляйте secrets/, sessions/, rollout — они могут содержать ваш код и промпты.

Полный сброс

Когда всё сломалось и хочется начать с чистого листа:

# Бэкап (опционально):
tar czf astracode-backup.tar.gz ~/.astracode/config.toml ~/.astracode/skills/

# Сносим всё:
rm -rf ~/.astracode

# Запуск с нуля:
astracode

⚠️ Это удалит все ваши сессии, секреты, память, custom скиллы.

Куда писать, если ничего не помогло

• /feedback в TUI (категория Bug).
• GitHub issues (если репо публичный).
• Внутренний чат команды (если корпоративный).