문제 해결
알파 시기의 일반적인 실패 모드와 복구 방법.
Kisenon은 알파 단계입니다. 여기 가장 마주칠 가능성이 높은 실패 모드와 각각을 넘어서는 방법이 있습니다.
엔드포인트가 Pending에서 멈춤
증상: 엔드포인트가 생성 시 몇 초 이상 Pending에 머뭅니다. 콘솔은
오류를 보여주지 않고, CLI는 같은 상태를 보여줍니다.
유력한 원인: 컴퓨트 파드를 스케줄링할 수 없습니다. 가장 흔한 이유는 클러스터 압박(요청된 CPU나 메모리가 비어 있는 노드가 없음) 또는 오래된 이미지 풀 자격 증명입니다. 둘 다 운영자 측 문제입니다.
할 일:
- 60초 기다리세요. 일시적인 압박은 보통 다른 엔드포인트가 일시 중지되면 해소됩니다.
- 해소되지 않으면, 엔드포인트를 삭제하고 다시 생성하세요. 컨트롤 플레인이 다른 노드에서 스케줄링을 재시도합니다.
- 다시 생성해도
Pending에 머문다면, 클러스터가 불안정한 것입니다. 엔드포인트 id와 벽시계 시간과 함께 GitHub 트래커에 보고를 제기하세요.
첫 연결 시 FATAL: endpoint unavailable
증상: psql이 막 생성된 엔드포인트로의 맨 첫 연결, 또는 긴 유휴 후에
FATAL: endpoint unavailable을 반환합니다.
유력한 원인: 콜드 스타트 경쟁 조건. 엔드포인트 상태는 Stopped이고,
당신의 패킷이 그것을 깨웠지만, 당신의 클라이언트가 포기할 때 Postgres가
여전히 브랜치 HEAD까지 WAL을 재생하는 중입니다.
할 일: 연결을 재시도하세요. 콜드 스타트는 일반적으로 300–500 ms에
완료되지만, 막 생성된 프로젝트의 맨 첫 깨우기, 또는 24시간 이상 유휴 후에는
pageserver 페이지 캐시가 따뜻해지는 동안 10–30초가 걸릴 수 있습니다.
대부분의 드라이버는 적어도 한 번의 재시도를 허용하면 이를 견딥니다. 원시
psql은 기본적으로 재시도하지 않습니다.
# psql with one explicit retry
for i in 1 2; do psql "$URI" -c '\q' && break; sleep 5; done엔드포인트가 30초 후에도 여전히 사용할 수 없으면, 파드 자체가 실패했을 수 있습니다 — 콘솔에서 상태를 확인하고 위의 Pending 안내를 참조하세요.
keon connection-string이 branch_not_found를 반환함
증상:
$ keon connection-string my-feature --project prj_abc...
Error: branch_not_found: my-feature…하지만 브랜치가 콘솔에 존재합니다.
유력한 원인: 이름이 당신이 대상으로 한 프로젝트의 브랜치와 일치하지
않습니다 — 보통 오타이거나, 잘못된 --project입니다. CLI는 위치 인수로
전달하든 --branch를 통해 전달하든 id 또는 이름으로 브랜치를 해석하므로,
실제로 존재하는 이름은 어느 쪽이든 해석됩니다.
할 일: 브랜치 이름과 프로젝트를 확인하세요:
keon branches list --project prj_abc...
keon connection-string my-feature --project prj_abc...로그인이 access_denied를 반환함
증상: Google 또는 GitHub OAuth가 완료되지만, 콘솔이 access_denied를
언급하는 오류 페이지로 리디렉션합니다.
유력한 원인: 알파 기간 동안 로그인은 이메일 허용 목록으로 제한됩니다. 당신의 주소가 온보딩되지 않았다면, 로그인 콜백이 원칙적으로 이를 거부합니다.
할 일: 알파 액세스에서 신청하세요. 당신의 주소가 허용 목록에 추가되면, 다음 시도에서 로그인이 정상적으로 완료됩니다.
콘솔 세션이 세션 도중에 만료됨
증상: 콘솔이 한동안 작동하다가, 갑자기 로그아웃하고 다시 로그인할 때까지 모든 API 호출에 401을 반환합니다.
유력한 원인: cp 서명 JWT가 만료되었고 그 갱신 창이 지났습니다. 콘솔은
수명이 짧은 JWT(약 15분)를 발행하고, 당신이 활성 상태인 동안
/v1/auth/refresh에 대해 백그라운드에서 갱신합니다. 갱신 창은 로그인으로부터
12시간으로 고정되어 있습니다: 활성 세션은 무기한 갱신되지만, 그 창을 넘어
손대지 않은 탭은 더 이상 갱신할 수 없습니다.
할 일: 로그아웃하고 다시 로그인하세요. 헤드리스 또는 장기 실행
자동화의 경우, 브라우저 세션 대신 nsk_ API 키를 사용하세요 — API 키는
만료되지 않으며 명시적으로 폐기됩니다. 인증을 참조하세요.
버그를 어디에 제기하나요
여기서 다루지 않은 모든 것의 경우:
- 제품 버그와 기능 요청: GitHub 트래커.
- 보안 취약점: 보안 — 공개 트래커에는 절대 안 됩니다.
구체적인 재현 단계, 영향을 받은 id(프로젝트, 브랜치, 엔드포인트), 그리고 벽시계 타임스탬프는 왕복 시간을 극적으로 단축합니다.