본문으로 건너뛰기

CLI 트러블슈팅

Caffeine CLI 사용 중 발생할 수 있는 문제와 해결 방법입니다.

🔍 일반적인 문제​

문제 1: "Not a valid project name" 에러​

증상:

❌ Invalid project name: Names starting with a digit are not allowed.

원인:

  • 프로젝트 이름이 숫자로 시작
  • 특수문자 포함
  • Windows 예약어 사용

해결책:

✅ 올바른 이름:

cafe init --name Driver2024         # 영문자로 시작
cafe init --name My-Driver          # 하이픈 사용 가능
cafe init --name Modbus_TCP_Driver  # 밑줄 사용 가능

❌ 잘못된 이름:

cafe init --name 2024Driver  # 숫자 시작 불가
cafe init --name My Driver!  # 공백 및 특수문자 불가
cafe init --name CON         # Windows 예약어 불가

프로젝트 이름 규칙:

  • 영문자로 시작 (A-Z, a-z)
  • 영문자, 숫자, 하이픈(-), 밑줄(_) 사용 가능
  • 공백 및 특수문자 (!@#$%^&*) 불가
  • Windows 예약어 불가 (CON, PRN, AUX, NUL, COM1-9, LPT1-9)

문제 2: "Directory already exists" 에러​

증상:

❌ Failed to create project: Directory 'MyDriver' already exists.

원인: 동일한 이름의 디렉토리가 이미 존재

해결책:

방법 1: 다른 이름 사용

cafe init --name MyDriver_v2

방법 2: 기존 디렉토리 제거

# Windows (PowerShell)
Remove-Item -Recurse -Force MyDriver

# Linux/macOS
rm -rf MyDriver

# 이후 재시도
cafe init --name MyDriver

방법 3: 다른 출력 경로 지정

cafe init --name MyDriver --output ./new_projects

문제 3: Git 초기화 실패​

증상:

⚠️  Git is not installed or not in PATH. Please install Git first.

원인: Git이 설치되지 않았거나 환경 변수 PATH에 없음

해결책:

Windows (PowerShell, 관리자 권한):

# Chocolatey 사용
choco install git

# 또는 공식 설치 프로그램
# https://git-scm.com/download/win

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install git

macOS (Homebrew):

brew install git

설치 확인:

git --version
# 출력 예: git version 2.42.0

PATH 확인 (Windows):

$env:PATH -split ';' | Select-String git

문제 4: Package 명령어가 스크립트를 찾지 못함​

증상:

❌ publish_local.ps1 script not found.
💡 Tip: Ensure publish_local.ps1 exists in scripts/ directory.

원인:

  • 잘못된 디렉토리에서 실행
  • 프로젝트 구조가 표준과 다름
  • 스크립트 파일이 없음

해결책:

1. 현재 위치 확인:

pwd
# 또는 Windows (PowerShell)
Get-Location

2. 스크립트 존재 확인:

ls scripts/publish_local.ps1
# 또는 Windows (PowerShell)
Test-Path scripts\publish_local.ps1

3. 올바른 디렉토리로 이동:

# 프로젝트 루트로 이동
cd ../..

# src 디렉토리의 프로젝트로 이동
cd src/MyDriver

# package 명령 실행
cafe package

4. 상대 경로 확인 (디버깅):

# 현재 위치에서 scripts 찾기
find . -name "publish_local.ps1"

# 또는 Windows (PowerShell)
Get-ChildItem -Recurse -Filter "publish_local.ps1"

문제 5: PowerShell Execution Policy 에러​

증상 (Windows):

File C:\path\to\publish_local.ps1 cannot be loaded because running scripts is disabled on this system.
For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.

원인: PowerShell 스크립트 실행 정책 제한

해결책:

임시 허용 (현재 세션만):

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

영구 허용 (사용자 수준, 관리자 권한):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

현재 정책 확인:

Get-ExecutionPolicy -List

보안 주의사항:

  • Bypass는 모든 스크립트 실행 (임시 사용 권장)
  • RemoteSigned는 로컬 스크립트 허용, 다운로드된 스크립트는 서명 필요 (권장)
  • AllSigned는 모든 스크립트 서명 필요 (높은 보안)

🔧 환경 관련 문제​

문제 6: .NET SDK 버전 오류​

증상:

❌ .NET SDK version 10.0 or higher is required, but found 8.0.100

원인: .NET SDK 버전이 낮음 (10.0 미만)

해결책:

1. 현재 버전 확인:

dotnet --version
dotnet --list-sdks

2. .NET 10.0 SDK 다운로드 및 설치:

3. 설치 확인:

dotnet --version
# 출력 예: 10.0.102

4. global.json 확인 (특정 버전 고정 시):

{
  "sdk": {
    "version": "10.0.0",
    "rollForward": "latestMinor"
  }
}

문제 7: Docker 연결 실패​

증상 (cafe doctor 실행 시):

❌ Docker: Not Available

원인:

  • Docker Desktop이 실행 중이 아님
  • Docker Engine이 설치되지 않음
  • Docker 소켓 권한 문제 (Linux)

해결책:

Windows/macOS:

  1. Docker Desktop 실행
  2. 시스템 트레이에서 Docker 아이콘 확인 (실행 중)
  3. 재시도: cafe doctor

Linux:

# Docker 설치 확인
docker --version

# Docker 서비스 시작
sudo systemctl start docker

# 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# 로그아웃 후 재로그인

Docker 연결 테스트:

docker ps

문제 8: 포트 충돌​

증상 (cafe doctor 실행 시):

⚠️  Redis (6379): In Use
⚠️  MQTT (1883): In Use
⚠️  Kafka (9092): In Use

원인: 해당 포트가 이미 다른 프로세스에서 사용 중

해결책:

포트 확인 (Windows PowerShell):

netstat -ano | findstr :6379
netstat -ano | findstr :1883
netstat -ano | findstr :9092

포트 확인 (Linux/macOS):

lsof -i :6379
lsof -i :1883
lsof -i :9092

해결 방법:

  1. 포트 사용 중 = 정상: 서비스가 이미 실행 중이므로 문제없음
  2. 충돌 해결 필요 시:
    • 기존 프로세스 종료
    • Caffeine 설정에서 다른 포트 사용

🐛 빌드 및 실행 문제​

문제 9: NuGet 복원 실패​

증상:

error NU1101: Unable to find package NEXCODE.Caffeine.Core. No packages exist with this id in source(s): nuget.org

원인: NuGet 패키지를 찾을 수 없음 (nuget.org 연결 불가 또는 패키지명 오류)

해결책:

1. NuGet 소스 확인:

dotnet nuget list source

2. NuGet.org 소스 활성화 확인:

dotnet nuget enable source nuget.org

3. 패키지 경로 확인 (Caffeine.Core.nupkg 위치):

# Windows (PowerShell)
Get-ChildItem -Recurse -Filter "NEXCODE.Caffeine.Core.*.nupkg"

# Linux/macOS
find / -name "NEXCODE.Caffeine.Core.*.nupkg" 2>/dev/null

4. 복원 재시도:

dotnet restore --force

문제 10: 빌드 오류 - "Type or namespace not found"​

증상:

error CS0246: The type or namespace name 'Caffeine' could not be found

원인: Caffeine.Core 패키지 참조 누락 또는 복원 실패

해결책:

1. .csproj 확인:

<ItemGroup>
  <PackageReference Include="NEXCODE.Caffeine.Core" Version="2.0.*" />
</ItemGroup>

2. 패키지 복원:

dotnet restore

3. 캐시 정리 후 재빌드:

dotnet clean
dotnet restore --no-cache
dotnet build

📞 추가 지원​

문제가 계속될 경우​

1. 로그 수집:

cafe doctor --verbose > doctor_log.txt
dotnet build --verbosity detailed > build_log.txt

2. 시스템 정보 수집:

# Windows (PowerShell)
Get-ComputerInfo | Select-Object OsName, OsVersion

# Linux
uname -a
lsb_release -a

# macOS
sw_vers

3. 기술 지원 요청:

4. 공식 문서:

📚 참고 자료​

작성일: 2026-01-28
버전: 2.0