AI용 분할본 · 지도 7단계(운영·개정 — 필요할 때만) — 어느 단계에서든 막히면 이 페이지를 연다 · 이 페이지 전에 읽을 페이지: PART 0 사용법·AI 시작 지침 · 코드 파일은 여기 없다 — 코드 자리의 줄을 따른다(폴더에 책 파일이 하나도 없는 처음이면 부록 A-2 의 curl 한 줄부터)

부록 D — 트러블슈팅

• 401 (우리 앱): 로그인 세션이 없는 것 — 정상 동작입니다. 로그인했는데도 곧바로 401이면 ① 쿠키 이름을 __Host-session으로 직접 지었거나 ② 세션 쿠키를 브라우저 JS(document.cookie)로 만든 것 — RIDM Apps 관문은 서버 응답의 Set-Cookie만 받아 줍니다. 앱은 평범한 session으로 서버에서만 굽고 읽습니다(5-1 lib/get-session-user.ts) ③ 관리자가 정지한 회원이면 로그인 자체가 403 "이용이 정지된 계정이에요"
• 메모 저장·삭제만 403: 요청에 Origin 이 없거나 앱 주소와 다른 것(7-2 방어선 3) — 화면에서 누르면 정상, curl 같은 도구로 시험하면 403 이 정상입니다. 실서버에서 화면으로 눌렀는데도 403 이면 smoke-live 가 "관문 뒤에서 Host 와 Origin 이 다르게 보임"으로 알려 주니 그 출력과 앱 주소를 contact@float.do 로 보냅니다
• 로그인·가입·로그아웃이 403 "허용되지 않는 요청이에요": 요청이 다른 주소에서 왔거나 본문이 JSON 이 아닌 것(로그인 CSRF 방어 — 7-2 방어선 3). 화면(lib/client.ts 의 sendJson/postJson)으로 부르면 정상입니다. 새 화면이 <form action="/api/auth/login"> 처럼 폼을 그대로 보내게 만들었다면 postJson 으로 바꿉니다
• 남의 메모를 열면 404: 정상입니다 — 남의 메모는 없는 메모와 똑같이 답합니다(6-1). 내 메모인데 404 면 다른 회원으로 로그인해 있는지 확인
• 400 "제목은 1~100자예요" / "내용은 5000자까지예요": 서버 한도(6-2). 공백만 있는 제목도 빈 제목입니다
• 413 "내용이 너무 길어요": 요청 본문이 64KB 를 넘음 — 화면을 거치지 않고 큰 본문을 보낸 것
• 429: 가입 제한(같은 IP 1시간 5회 — smoke-live 를 너무 자주 돌린 경우 흔함, 1시간 뒤 다시), 새 메모 제한(회원당 1분 30개·하루 50개·합계 200개, 고치기·지우기 합쳐 1분 60회 — 한 회원이 DB 를 채우지 못하게 하는 한도, 6-2. 200개면 안 쓰는 메모를 지우면 됩니다), 로그인·복구·탈퇴 실패 제한(15분) — 모두 정상 동작. 한도는 책 코드라 늘리지 않습니다
• 주소에 들어가면 503 "앱이 대기 중입니다": 무료 플랜 앱이 잠든 상태에서 HEAD나 curl 기본 User-Agent로 확인한 것 — 브라우저로 열거나 curl -s -A "Mozilla/5.0" 처럼 브라우저 User-Agent를 붙이면 깨어납니다(8-3). 브라우저인데도 계속 503이면 앱 카드 상태(시작 실패·정지)를 확인
• 배포 기록이 "실패": 그 줄의 빌드 로그 끝부분을 봅니다. 루트에 Dockerfile 없음·package-lock.json 미커밋·next build 타입 에러가 대부분(8-2 표)
• 빌드 실패 secrets found in the repository: 배포 기록에 나온 파일·줄을 봅니다. .env.example에 예시 비밀번호가 든 DB 주소를 적은 경우가 대부분 — 값을 비우고 push(8-2 표)
• push 했는데 실서버가 그대로: push 는 배포가 아닙니다. /api/health 의 commit 이 옛 커밋이면 새 빌드가 실패했거나 아직 자동 승인 중 — 콘솔 → 내 앱 → 배포 기록에서 그 커밋 줄의 상태·사유를 봅니다(8-2 표)
• "호스팅 시작하기"가 안 됨: 콘솔 이메일 인증을 안 마쳤거나(1-1), 무료 플랜 앱이 이미 하나 있음(파트너당 1개 — 9-1)
• "화면이 책 컴포넌트를 안 씀 components/Notes.tsx"(또는 DeleteAccount.tsx): verify-book-code 가 첫 화면이 책의 메모·탈퇴 컴포넌트를 쓰지 않는다고 알려 준 것 — 자작 화면을 지우고 app/page.tsx 에서 @/components/Notes·@/components/DeleteAccount 를 불러 씁니다(6-3, 5-4)
• "관리자 주소가 코드에 들어갔어요": verify-book-code 가 파일 속에서 admin+숫자 24자리를 찾은 것 — 그 줄을 지우고 커밋합니다. 이미 push 했다면 make-admin-path 로 새 주소를 만들어 바꿉니다(B-7)
• "시작 실패": 10초 안에 /가 응답 안 함, 읽기 전용 파일시스템에 쓰기 시도(/tmp만 가능), 메모리 초과. 로컬에서 docker run --read-only --tmpfs /tmp -p 3000:3000 이미지로 재현
• API 500 + DATABASE_URL is not set: 로컬 실행에서 .env.local에 로컬 Postgres 주소를 안 넣은 것(7-5). RIDM Apps에서는 플랫폼이 자동으로 넣어 주니 직접 넣지 마세요(예약 이름이라 저장도 거부됩니다)
• 가입·로그인·메모가 전부 500: 내 테이블(lib/schema-extra.ts)의 문장이 틀린 것 — 책 테이블은 남지만 고칠 때까지 DB 를 쓰는 모든 요청이 실패합니다. 테스트 DB 로 npx vitest run tests/db.test.ts 를 돌려 어느 문장인지 찾습니다(부록 E)
• DB 에러 too many clients: 앱 DB 연결은 3개까지 — lib/db.ts의 Pool max: 2를 늘리지 말고, 새 라우트가 요청마다 새 Pool을 만들고 있지 않은지 확인(쿼리는 전부 lib/db.ts 의 sql() 로)
• DB 쓰기가 갑자기 전부 실패: 플랜 DB 용량을 넘긴 채 24시간이 지나(150% 초과면 즉시) 읽기 전용이 된 것입니다. 이 상태에서는 앱 화면의 삭제도 실패합니다(연결 기본값이 읽기 전용). 읽기 전용인 채 110%를 넘으면 DB 연결 자체가 끊깁니다. 가장 빠른 해결은 플랜 올리기이고, 행을 지우려면 그 연결에서 SET default_transaction_read_only = off 를 먼저 실행해야 합니다. 용량이 90% 아래로 내려가거나 플랜을 올리면 5분 안에 풀립니다(부록 E-2)
• 메모 화면이 폰에서 옆으로 넘침: components/Notes.module.css 나 app/globals.css 를 고치다 고정 폭(width: 500px, 100vw)을 넣은 것 — minmax(0, 1fr)·width: 100% 로 되돌리고 390px 에서 scrollWidth === clientWidth 확인
• 로컬 smoke-live 가 가입에서 429: 로컬 앱을 재시작하면 제한 숫자가 초기화됩니다(메모리) — 실서버에서는 1시간 기다립니다

AI용 분할본 · 지도 7단계(운영·개정 — 필요할 때만) — 어느 단계에서든 막히면 이 페이지를 연다 · 이 페이지 전에 읽을 페이지: PART 0 사용법·AI 시작 지침 · 코드 파일은 여기 없다 — 코드 자리의 줄을 따른다(폴더에 책 파일이 하나도 없는 처음이면 부록 A-2 의 curl 한 줄부터)