Integ Docs | API

Appearance

Частые ошибки и решения ​

Справочник по типичным проблемам при работе с Integ API и способам их решения.

Проблемы запуска ​

Docker контейнер не запускается ​

Симптомы:

Error: Cannot connect to the Docker daemon

Решение:

bash
# macOS: запустить Docker Desktop
open -a Docker

# Linux: запустить Docker service
sudo systemctl start docker

# Проверить статус
docker info

Порт 5435 занят ​

Симптомы:

Error: bind: address already in use

Решение:

bash
# Найти процесс на порту
lsof -i :5435

# Остановить процесс
kill -9 <PID>

# Или изменить порт в docker-compose.yml
ports:
  - "5433:5432"  # Использовать другой порт

База данных не готова ​

Симптомы:

Error: Connection refused to localhost:5435

Решение:

bash
# Подождать пока контейнер запустится
sleep 5

# Проверить статус контейнера
docker ps

# Проверить логи PostgreSQL
docker logs postgres

Проблемы с миграциями ​

Миграция не применяется ​

Симптомы:

No migrations are pending

Решение:

bash
# Проверить статус миграций
npm run typeorm -- migration:show

# Если миграция уже применена, но нужно повторить:
npm run migration:revert
npm run migration:run

Конфликт миграций ​

Симптомы:

Error: relation "table_name" already exists

Решение:

bash
# 1. Откатить последнюю миграцию
npm run migration:revert

# 2. Проверить и исправить миграцию

# 3. Применить заново
npm run migration:run

# Если нужно сбросить всё (ОСТОРОЖНО - удалит данные):
docker exec -it postgres psql -U postgres -d integ -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
npm run migration:run

Entity не синхронизирована ​

Симптомы:

QueryFailedError: column "new_column" does not exist

Решение:

bash
# 1. Сгенерировать миграцию для новых изменений
npm run migration:generate -- src/migrations/SyncEntity

# 2. Применить
npm run migration:run

Проблемы TypeScript ​

Cannot find module ​

Симптомы:

typescript
Cannot find module '@app/shared/utils' or its corresponding type declarations

Решение:

bash
# Проверить tsconfig.json paths
cat tsconfig.json | grep -A 10 "paths"

# Пересобрать
npm run build

# Или перезапустить TypeScript server в IDE
# VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server"

Type error после обновления ​

Симптомы:

error TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'

Решение:

bash
# 1. Проверить типы
npm run typecheck

# 2. Очистить кэш TypeScript
rm -rf node_modules/.cache

# 3. Переустановить зависимости если нужно
rm -rf node_modules
npm install

Проблемы ESLint ​

Unexpected token ​

Симптомы:

Parsing error: Unexpected token

Решение:

bash
# Проверить версию ESLint
npm list eslint

# Обновить ESLint config
npm run lint:fix

# Если проблема в конфигурации:
cat eslint.config.mjs

Too many errors ​

Симптомы:

ESLint found too many errors (100+)

Решение:

bash
# Исправить автоматически
npm run lint:fix

# Удалить комментарии и return types
npm run removeComments
npm run removeReturnTypes

# Проверить оставшиеся ошибки
npm run lint

Проблемы API ​

401 Unauthorized ​

Симптомы:

json
{
	"statusCode": 401,
	"message": "Unauthorized"
}

Решения:

bash
# 1. Проверить токен
curl http://localhost:3000/api/auth/me \
  -H "Authorization: Bearer $TOKEN"

# 2. Получить новый токен
curl -X POST http://localhost:3000/api/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}'

# 3. Проверить формат заголовка
# Правильно: Authorization: Bearer <token>
# Неправильно: Authorization: <token>

403 Forbidden ​

Симптомы:

json
{
	"statusCode": 403,
	"message": "Forbidden resource"
}

Решения:

bash
# 1. Проверить права пользователя
# 2. Проверить что ресурс принадлежит текущему пользователю
# 3. Проверить роли и permissions

404 Not Found ​

Симптомы:

json
{
	"statusCode": 404,
	"message": "Not Found"
}

Решения:

bash
# 1. Проверить URL эндпоинта
curl -v http://localhost:3000/api/integrations

# 2. Проверить что ID существует
curl http://localhost:3000/api/integrations \
  -H "Authorization: Bearer $TOKEN"

# 3. Проверить маршруты в контроллере

500 Internal Server Error ​

Симптомы:

json
{
	"statusCode": 500,
	"message": "Internal server error"
}

Решения:

bash
# 1. Проверить логи приложения
npm start  # Смотреть в консоль

# 2. Проверить логи Docker
docker logs integ-api

# 3. Проверить подключение к БД
docker exec -it postgres psql -U postgres -c "SELECT 1"

Проблемы окружения ​

Environment файл не найден ​

Симптомы:

Error: Cannot find environment file

Решение:

bash
# Сгенерировать environment
npm run generate:env:local

# Проверить что файл создан
ls -la src/environments/environment.ts

Doppler не настроен ​

Симптомы:

Error: Doppler CLI not found or not configured

Решение:

bash
# Установить Doppler (macOS)
brew install dopplerhq/cli/doppler

# Авторизоваться
doppler login

# Настроить проект
doppler setup

# Проверить
doppler secrets

Неверные переменные окружения ​

Симптомы:

Error: Invalid database credentials

Решение:

bash
# Проверить переменные
cat src/environments/environment.ts

# Пересгенерировать
npm run generate:env:local

# Проверить Doppler
doppler secrets --project integ-api --config local

Проблемы Git ​

Pre-commit hook failed ​

Симптомы:

husky - pre-commit hook exited with code 1

Решение:

bash
# 1. Исправить ошибки линтинга
npm run lint:fix

# 2. Удалить комментарии и return types
npm run removeComments:staged
npm run removeReturnTypes:staged

# 3. Отформатировать
npx pretty-quick --staged

# 4. Повторить коммит
git add .
git commit -m "message"

Pre-push hook failed ​

Симптомы:

husky - pre-push hook exited with code 1

Решение:

bash
# 1. Проверить типы
npm run typecheck

# 2. Проверить линтинг
npm run lint

# 3. Проверить сборку
npm run build

# 4. Исправить ошибки и повторить push

Merge conflict ​

Симптомы:

CONFLICT (content): Merge conflict in file.ts

Решение:

bash
# 1. Открыть файл и разрешить конфликты вручную

# 2. Или использовать инструмент merge
git mergetool

# 3. После разрешения
git add .
git commit -m "resolve merge conflicts"

Быстрая диагностика ​

Чеклист при проблемах ​

bash
# 1. Docker работает?
docker ps

# 2. БД доступна?
docker exec -it postgres psql -U postgres -c "SELECT 1"

# 3. Environment настроен?
cat src/environments/environment.ts

# 4. Миграции применены?
npm run typeorm -- migration:show

# 5. TypeScript компилируется?
npm run typecheck

# 6. ESLint проходит?
npm run lint

# 7. Приложение запускается?
npm start

Полный сброс (крайний случай) ​

Внимание

Это удалит все локальные данные!

bash
# 1. Остановить всё
npm run docker:down

# 2. Удалить volumes
docker volume rm integ-api_postgres_data

# 3. Удалить node_modules
rm -rf node_modules

# 4. Переустановить
npm install

# 5. Запустить заново
npm run docker:up
npm run generate:env:local
npm run migration:run
npm start

Связанные документы ​