Troubleshooting¶
FAQ и решение типичных проблем.
Генерация¶
Ошибка "main.name is required"¶
Причина: Отсутствует обязательное поле main.name в конфигурации.
Решение:
Ошибка "duplicate rest name"¶
Причина: Два REST транспорта с одинаковым именем и версией.
Решение: Используйте уникальные комбинации name + version:
Файлы не генерируются¶
Причина: Неправильный путь к target директории.
Решение:
# Используйте абсолютный путь
go-project-starter --config=config.yaml --target=/home/user/my-project
# Или убедитесь, что директория существует
mkdir -p ./my-project
go-project-starter --config=config.yaml --target=./my-project
Удалённые спеки¶
См. также: Удалённые спеки.
'git' executable not found in PATH¶
Причина: В path: указан git+ssh:// или git+https://, но git не установлен.
Решение: Установите git (brew install git / apt-get install git). Если используете только локальные пути или https:// — git не нужен.
token_env variable is empty: GITHUB_TOKEN¶
Причина: В URI указан ?token_env=GITHUB_TOKEN, но переменная не экспортирована.
Решение:
git clone failed: authentication failed (для git+ssh://)¶
Причина: ssh-agent не запущен или ключ не добавлен.
Решение:
ssh-add -l # проверить, какие ключи доступны
ssh-add ~/.ssh/id_ed25519 # добавить ключ
ssh -T git@github.com # проверить доступ
git clone failed: repository not found¶
Причина: Опечатка в URL или нет прав на репозиторий.
Решение: Проверьте URL и сделайте git clone <repo> локально.
subpath not found in repository: <path>¶
Причина: Файл по #subpath отсутствует в склонированном репо.
Решение: Сообщение содержит подсказку с похожими именами файлов — поправьте путь в YAML или укажите правильный <ref>.
directory subpaths are not supported yet¶
Причина: В git-URI указан subpath, заканчивающийся на / (директория). v1 поддерживает только файлы.
Решение: Укажите конкретный файл, например #openapi/users.yaml.
Ogen: ошибки компиляции¶
"undefined: oas.ErrorDefault" или "undefined: oas.ErrorDefaultStatusCode"¶
Причина: В OpenAPI-спецификации отсутствует схема ErrorDefault или она имеет другое имя/структуру. Генератор ожидает, что ogen создаст типы ErrorDefault и ErrorDefaultStatusCode с конкретными полями.
Решение: Добавьте в components.schemas вашей OpenAPI-спецификации:
components:
schemas:
ErrorDefault:
required:
- code
- error
properties:
code:
type: integer
format: int32
error:
type: string
type: object
И используйте $ref: '#/components/schemas/ErrorDefault' в default ответах endpoints.
Что генерирует ogen из этой схемы:
ErrorDefault— struct{ Code int32; Error string }с методомEncode(e *jx.Encoder)ErrorDefaultStatusCode— struct{ StatusCode int; Response ErrorDefault }
Оба типа используются в сгенерированных файлах error_response.go, handler/handler.go и router.go.
"errResp.Encode undefined" или "errResp.Code undefined"¶
Причина: Схема ErrorDefault определена, но с другими полями. Генератор ожидает поля code (int32) и error (string).
Решение: Проверьте, что структура схемы точно соответствует примеру выше. Поля code и error — обязательны и должны быть именно такого типа.
Сборка проекта¶
"cannot find package"¶
Причина: Зависимости не загружены.
Решение:
"undefined: ogen"¶
Причина: Ogen код не сгенерирован.
Решение:
toolchain upgrade needed to resolve <модуль>¶
go: toolchain upgrade needed to resolve go.opentelemetry.io/otel/exporters/otlp/otlptrace
go: ...@v1.47.0 requires go >= 1.26.0 (running go 1.24.4; GOTOOLCHAIN=local)
Причина: go mod tidy резолвит не только импорты проекта, но и импорты
тестов зависимостей. Если такой пакет не требуется ни одним модулем в графе,
tidy берёт его @latest — а @latest может требовать Go новее, чем
tools.golang_version проекта. Под GOTOOLCHAIN=local (так настроены
официальные golang:* образы) подняться до нужного тулчейна нельзя, и tidy
падает. Шаг post_generate: go_mod_tidy при этом прерывает генерацию.
Решение: запинить проблемный модуль в go.mod на версию, совместимую с
вашей tools.golang_version — обычно это версия из той же релизной линейки,
что и уже присутствующие в go.mod соседние модули:
require (
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.33.0 // indirect
go.opentelemetry.io/proto/otlp v1.4.0 // indirect
)
Для goat-проектов такие пины уже входят в шаблон go.mod — подробнее
см. Go Version Policy.
Приватные модули не загружаются¶
Причина: Не настроен GOPRIVATE.
Решение: Добавьте в конфигурацию:
Docker¶
"Cannot connect to Docker daemon"¶
Причина: Docker не запущен.
Решение:
"port is already allocated"¶
Причина: Порт занят другим процессом.
Решение:
# Найти процесс
lsof -i :8080
# Или изменить порт в docker-compose
# Или остановить conflicting контейнер
docker compose down
Dev Stand¶
OnlineConf updater не создаёт TREE.cdb¶
Причина: Проблемы с MySQL или Admin UI.
Решение:
# Проверить логи
docker compose -f docker-compose-dev.yaml logs onlineconf-updater
docker compose -f docker-compose-dev.yaml logs onlineconf-database
# Пересоздать окружение
make dev-drop
make dev-up
Изменения в init-config.sql не применяются¶
Причина: MySQL выполняет init-скрипты только при первом запуске.
Решение:
Submodule не инициализирован¶
Причина: OnlineConf submodule не загружен.
Решение:
Тесты¶
"API did not become ready"¶
Причина: Приложение не запустилось.
Решение:
- Проверьте бинарник:
ls -la /tmp/api - Проверьте Docker:
docker ps - Посмотрите логи:
tail -f /tmp/yourproject-test-*.log
"Database connection refused"¶
Причина: Testcontainers не запустили PostgreSQL.
Решение:
- Проверьте Docker daemon
- Проверьте права на Docker socket
- Увеличьте таймаут запуска
"TestEnvInitializer not implemented"¶
Причина: Не создан файл tests/init.go либо реализация в нём не зарегистрирована.
Решение: Создайте файл с реализацией интерфейса и зарегистрируйте её инициализатором
переменной — var _ = SetTestEnvInitializer(&testEnvInitializerImpl{}) (см.
GOAT). Присваивание testEnvInit из init() в сгенерированных
проектах запрещено линтером gochecknoinits.
CI/CD¶
"permission denied" в GitHub Actions¶
Причина: Неправильные секреты или права.
Решение:
- Проверьте секреты в Settings → Secrets
- Убедитесь, что SSH ключ правильный
- Проверьте права на registry
Docker push fails¶
Причина: Неверные credentials для registry.
Решение:
# GitHub Container Registry
gh secret set GHCR_USER --body "username"
gh secret set GHCR_TOKEN --body "ghp_..."
# Проверьте локально
docker login ghcr.io -u username -p token
Общие советы¶
Предпросмотр изменений¶
Используйте --dry-run перед генерацией:
Логирование¶
Включите debug логирование:
Версии инструментов¶
Убедитесь, что версии совместимы:
Очистка и перегенерация¶
При серьёзных проблемах:
# Сохраните ваш код
cp -r internal/app/*/transport/rest/*/handler.go /tmp/backup/
# Удалите сгенерированные файлы
rm -rf cmd/ internal/ pkg/ Makefile Dockerfile docker-compose.yaml
# Перегенерируйте
go-project-starter --config=config.yaml
# Восстановите ваш код
cp /tmp/backup/*.go internal/app/*/transport/rest/*/
Получение помощи¶
Если проблема не решена:
- Проверьте GitHub Issues
- Создайте новый issue с:
- Версия генератора (
go-project-starter --version) - Конфигурация (без секретов)
- Полный вывод ошибки
- Шаги воспроизведения