문제 해결

먼저 문제가 Melso 서비스, 데몬, 런타임, AI 코딩 도구 중 어느 계층에서 발생하는지 확인하세요. 다음 명령만으로도 첫 번째 유효한 오류를 찾을 수 있는 경우가 많습니다.

melso version
melso auth status
melso daemon status --output json
melso daemon logs --lines 100

자체 호스팅 인스턴스에서는 서비스를 직접 확인할 수도 있습니다.

curl -i https://api.example.com/health
curl -i https://api.example.com/readyz

/health는 API 프로세스가 응답한다는 것만 확인하고, /readyz는 데이터베이스와 migration도 확인합니다. 문제를 신고할 때는 오류, 관련 로그, CLI 버전, 운영체제를 포함하고 token과 이메일 같은 민감 정보는 제출 전에 제거하세요.

데몬 연결 실패

먼저 다음을 실행합니다.

melso auth status
melso daemon status --output json
melso daemon logs --lines 100

일반적인 원인은 다음과 같습니다.

• CLI에 아직 로그인하지 않았거나 로컬에 저장된 token이 만료됨
• 데몬이 잘못된 Melso 서비스에 연결됨
• 실행 컴퓨터에서 API에 접근할 수 없거나 DNS, TLS, 방화벽이 연결을 차단함
• 현재 계정이 대상 워크스페이스에서 나감
• 로컬에 지원되는 AI 코딩 도구가 하나도 설치되지 않아 데몬을 시작할 수 없음

다시 로그인하고 데몬을 다시 시작합니다.

melso login
melso daemon restart

자체 호스팅 환경에서는 실행 컴퓨터에서 API의 /health도 요청해야 합니다. 서버 컴퓨터에서의 테스트만으로는 실행 컴퓨터 측 DNS, TLS, 방화벽 문제를 찾을 수 없습니다. 주소를 바꿔야 하면 melso setup self-host를 다시 실행하거나 현재 profile의 server_url을 확인하세요.

melso config show

이슈 실행이 시작되지 않음

이슈의 실행 로그를 열고 실행 태스크의 현재 상태와 대기 이유를 먼저 확인합니다.

queued 상태

queued는 실행 태스크가 런타임에 수령되기를 기다리고 있다는 뜻입니다. 다음 순서로 확인하세요.

1. 에이전트에 연결된 런타임이 온라인인지
2. 런타임이 에이전트에 설정된 AI 코딩 도구를 감지했는지
3. 에이전트에 사용 가능한 동시 실행 용량이 남아 있는지
4. 데몬에 전체 실행 용량이 남아 있는지

에이전트 한 명은 기본적으로 실행 태스크를 최대 6개까지 동시에 실행하고 데몬 하나는 최대 20개까지 실행합니다. 상한에 도달하면 새 실행 태스크는 큐에 남아 기존 실행이 끝난 뒤 시작됩니다. 런타임이 오프라인이어도 실행 태스크는 계속 대기하며 2시간 넘게 수령되지 않을 때만 실패합니다.

melso daemon status --output json
melso agent get <agent-id>
melso issue runs <issue-id>

런타임 목록에 예상한 도구가 없다면 같은 시스템 계정과 PATH에서 도구가 실행되고 로그인되어 있는지 확인한 뒤 melso daemon restart를 실행합니다.

waiting_local_directory 상태

다른 실행 중 태스크가 같은 로컬 디렉터리를 사용하고 있다는 뜻입니다. Melso는 두 에이전트가 같은 파일을 동시에 수정하지 않도록 디렉터리 잠금이 해제되기를 기다립니다.

이 대기는 디렉터리의 in_place("직접") 모드에서만 발생합니다. 디렉터리가 git 저장소라면 리소스를 worktree("병렬")로 전환하면 대기열 자체가 사라집니다. 각 작업이 자기 워크트리를 받고 결과를 브랜치로 돌려주므로 어느 작업도 기다리지 않습니다. 프로젝트 리소스를 참고하세요.

그렇지 않으면 일반적으로 앞선 실행 태스크가 끝날 때까지 기다리면 됩니다. 앞선 태스크가 멈췄다면 해당 실행 로그에서 중지할 수 있고, 현재 에이전트에 다른 로컬 디렉터리를 선택할 수도 있습니다. 이 디렉터리 상호 배제는 데몬이 메모리에서 관리하며 디스크에 lock 파일을 쓰지 않습니다. 잠금 상태가 비정상이라고 의심되면 melso daemon restart를 실행해 해제하세요. 직접 삭제해야 할 파일은 없습니다.

AI 코딩 도구 시작 실패

데몬이 온라인이어도 도구 자체를 사용할 수 있다는 뜻은 아닙니다. 이번 실행의 상세 기록을 열고 다음 항목을 중점적으로 확인하세요.

• 도구 로그인이 완료되었는지
• API key, 사용량, 모델 권한을 사용할 수 있는지
• 에이전트가 선택한 모델과 사고 단계가 해당 도구에서 지원되는지
• 로컬 작업 디렉터리가 존재하고 쓰기 가능한지
• 에이전트의 사용자 지정 인수와 환경 변수가 유효한지

먼저 실행 컴퓨터의 터미널에서 같은 도구를 직접 실행하세요. 도구 자체도 시작할 수 없다면 도구 로그인 또는 설정을 먼저 수정하고 실행 로그에서 실행 태스크를 재시도합니다.

실시간 업데이트가 작동하지 않음

태스크는 실행되지만 댓글과 상태가 실시간으로 나타나지 않는다면 일반적으로 WebSocket이 연결되지 않은 것입니다.

브라우저 개발자 도구의 Network → WS에서 /ws 연결을 확인합니다. 자체 호스팅 환경에서는 특히 다음 항목을 확인하세요.

• FRONTEND_ORIGIN이 브라우저에서 실제로 연 주소와 같은지
• HTTPS 페이지가 wss://로 연결되는지
• reverse proxy가 WebSocket Upgrade 요청을 전달하는지
• 브라우저 로그인이 만료되었는지

컨테이너는 생성될 때만 .env를 읽으므로 수정 후 다시 생성해야 합니다.

docker compose -f docker-compose.selfhost.yml up -d

전체 reverse proxy 예시는 자체 호스팅 빠른 시작을 참고하세요.

인증 코드 및 초대 이메일이 도착하지 않음

먼저 backend 시작 로그를 확인합니다. 로그에는 현재 SMTP relay, Resend API, DEV mode 중 무엇을 사용하는지 표시됩니다.

docker compose -f docker-compose.selfhost.yml logs backend \
  | grep "EmailService:"

• DEV mode: 이메일을 보내지 않고 인증 코드와 초대 링크를 backend 로그에만 기록합니다.
• Resend: API key가 유효하고 발신 주소의 도메인이 인증되었는지 확인합니다.
• SMTP: host, port, 자격 증명, 발신 주소를 확인하고 오류 로그에서 연결, TLS, 인증, 전달 중 어느 단계에서 실패했는지 판단합니다.

SMTP_HOST와 Resend를 함께 설정하면 Melso가 SMTP를 우선 사용합니다. 설정 방법은 로그인과 가입을 참고하세요.

첨부 파일 업로드 또는 다운로드 실패

먼저 backend 로그와 응답 status code를 확인합니다. 일반적인 원인은 다음과 같습니다.

• reverse proxy의 요청 body 크기 제한
• 로컬 업로드 디렉터리에 쓸 수 없거나 persistent volume을 mount하지 않음
• S3 bucket, region, endpoint, 자격 증명이 일치하지 않음
• 다운로드 주소가 proxy를 통과한 뒤 잘못된 공개 도메인 또는 프로토콜을 사용함

Docker Compose를 사용하면 기본 backend_uploads volume에 로컬 첨부 파일이 저장됩니다. 컨테이너를 다시 만들어도 삭제되지 않지만 docker compose down -v는 data volume을 삭제합니다. S3 설정은 환경 변수를 참고하세요.

사용량(Usage)이 0으로 표시됨

Usage 페이지는 각 실행 태스크의 원본 사용량을 직접 읽지 않고 시간별 집계 데이터를 읽습니다. 먼저 원본 데이터와 집계 테이블을 확인합니다.

SELECT count(*) FROM task_usage;
SELECT count(*) FROM task_usage_hourly;

SELECT plan_time, status, error_code, error_msg
FROM sys_cron_executions
WHERE job_name = 'rollup_task_usage_hourly'
ORDER BY plan_time DESC
LIMIT 20;

task_usage에 데이터가 있지만 집계 테이블이 비어 있고 스케줄 기록에 실패가 표시된다면 migration이 모두 적용되었는지 먼저 확인하세요. 업그레이드가 migration 103에서 거부되는 경우는 다음 절을 참고하세요. 집계 함수를 직접 한 번 실행해 SQL 문제인지 스케줄 문제인지 구분할 수도 있습니다.

SELECT rollup_task_usage_hourly();

수동 실행 후 숫자가 정상이라면 집계 함수는 사용할 수 있고 backend 정기 스케줄에 문제가 있는 것입니다. 수동 SQL은 집계를 한 번만 보충하며 스케줄을 복구하지 않습니다. 시간별 집계는 backend 내장 스케줄러가 실행하므로 pg_cron을 직접 설정할 필요가 없습니다.

업그레이드할 때 migration 103이 실행을 거부함

정상 업그레이드에서는 migration 103을 위해 따로 할 일이 없습니다. migrate up은 migration을 적용하기 전에 이전 사용량 데이터를 자동으로 backfill합니다. 빈 데이터베이스는 바로 통과하고 이전 데이터가 있는 인스턴스는 월별로 자동 보충한 뒤 계속 진행합니다.

backend 시작 중 refusing to drop legacy daily rollups 오류가 계속 발생하면 자동 backfill이 완료되지 않은 것입니다. 예를 들어 도중에 실패했거나 migrate up을 사용하지 않고 SQL을 직접 적용했을 수 있습니다. 이때는 backfill 명령을 직접 실행하고 완료된 뒤 backend를 다시 시작하세요.

cd server
DATABASE_URL='postgres://...' go run ./cmd/backfill_task_usage_hourly

자주 쓰는 flag: --dry-run은 쓰지 않고 미리 보기만 하며, --sleep-between-slices는 slice 사이에 간격을 두어 사용량이 많은 인스턴스의 읽기 부하를 낮춥니다. 명령은 월별 slice로 실행되고 멱등성을 가지므로 중단 후 바로 다시 실행할 수 있습니다. advisory lock을 보유해 서버의 정기 집계와 상호 배제되므로 중복되거나 일관되지 않은 집계 데이터가 생기지 않습니다. 완료 후 backend를 다시 시작하고 /readyz에서 migrations가 ok인지 확인하세요.

포트 사용 중

로컬에서 자주 사용하는 port는 API의 8080, Web의 3000, 데몬 health check port입니다. 먼저 사용 중인 프로세스를 찾습니다.

lsof -nP -iTCP:8080 -sTCP:LISTEN   # macOS / Linux
netstat -ano | findstr :8080       # Windows

다른 Melso checkout이 사용 중이라면 해당 디렉터리에서 make stop을 먼저 실행합니다. 그렇지 않다면 port를 사용 중인 프로그램을 정상적으로 중지하거나 현재 서비스 port를 변경합니다. 공개 인터넷의 80/443은 Caddy, Nginx 같은 reverse proxy가 사용합니다.

로그 위치

어떤 파일이 현재 사용 중인 로그인지는 데몬을 시작한 profile에 따라 달라집니다. 이전 데몬이 남긴 오래된 로그도 문제없이 읽히기 때문에 엉뚱한 파일을 보게 되기 쉽습니다. 추측으로 파일을 열지 말고 melso daemon logs를 사용하세요. 내용을 출력하기 전에 해석한 절대 경로를 먼저 표시합니다. 이름 있는 profile의 로그는 --profile <name>을 붙여서 확인합니다.

데몬 시작 과정을 직접 확인해야 한다면 foreground에서 실행합니다.

melso daemon stop
melso daemon start --foreground

그래도 원인을 찾지 못하면 GitHub Issues에서 기존 문제를 검색하거나 새 이슈를 제출하세요.

다음 단계

• 데몬과 런타임 — 런타임 등록과 온라인 상태 메커니즘을 알아봅니다.
• 실행 태스크 — 상태, timeout, 실패 원인을 확인합니다.
• 환경 변수 — 자체 호스팅 설정 전체를 참고합니다.