CLI 오류 해결 가이드
실제 오류 문구로 설치·연결·빌드·실행·DB·제출 문제의 원인과 복구 절차를 찾습니다.
CLI 오류 해결 가이드
앱 폴더에서 nexia status로 프로젝트와 인증 상태를 먼저 확인하세요.
터미널 오류 문구를 이 페이지에서 검색하세요. 아래 명령의 <project-id>, <submission-id>, <request-id>는 실제 값으로 바꾸며 꺾쇠괄호는 입력하지 않습니다. .nexia에는 기존 연결과 요청을 복구할 정보가 있으므로 삭제하지 않습니다.
프로젝트 폴더는 앱들을 담는 상위 폴더이고, 앱 폴더는 nexia.json과 composer.json이 있는 하위 폴더입니다. 연결·전체 개발은 프로젝트 폴더에서, 의존성 설치·앱 검사·DB 작업은 대상 앱 폴더에서 실행합니다.
증상별 해결
| 증상 | 할 일 | 확인할 결과 |
|---|---|---|
nexia 명령을 찾지 못함 | Node.js 22.12+, npm 11.x를 준비하고 npm install -g @nexia/cli@alpha 실행. 터미널을 다시 열고 npm 실행 경로 확인 | nexia --version에 버전 표시 |
| PHP·생성 도구 준비 실패 | PHP 8.5.12+와 Composer를 확인한 뒤 nexia setup --devtools 실행 | 생성 도구 준비 완료 |
| 로그인 만료·브라우저가 열리지 않음 | 연결된 프로젝트 폴더에서 nexia login --no-browser 실행 후 출력 URL에서 승인 | nexia status에 원하는 프로젝트와 인증 표시 |
| 폴더가 프로젝트에 연결되지 않음 | 프로젝트 폴더에서 Console에 표시된 nexia connect <project-id> 실행 | 연결 대상 프로젝트 일치 |
| 앱이 없거나 로컬 의존성 누락 | 앱을 프로젝트 바로 아래에 두고 앱 폴더에서 composer install --no-scripts, npm install 실행 | CLI가 앱을 발견하고 프런트엔드 빌드 완료 |
App execution failed | 실패 코드·단계·담당 영역·이슈 코드를 확인. App 코드로 확인된 경우에만 소스를 수정하고, 플랫폼 DB·라우팅 실패는 플랫폼 복구를 기다림. dev는 계속 실행 | 다음 실행이 준비 완료로 표시됨 |
| 샌드박스 만료·준비 실패 | Console의 샌드박스 관리에서 상태와 복구 안내 확인. 만료는 연장하고, 삭제 전 데이터 손실 안내 확인 | 샌드박스 준비 완료 |
| 다른 프로젝트의 샌드박스가 있음 | Console의 기존 샌드박스 보기에서 대상 확인. 계정당 활성 샌드박스는 하나 | 사용할 프로젝트의 샌드박스 확인 |
| 메뉴가 없거나 접근이 거부됨 | 워크스페이스 설정 → 자격 증명 및 접근에서 필요한 권한·법인 선택. 권한 자체가 없으면 앱 선언 반영 문제 해결 확인 | 허용한 사용자가 화면 조회·저장 가능 |
| DB 작업이 대기·실패함 | nexia db status 확인. dev는 켜 두며 명시적 DB 명령이 진행 중 준비를 기다림. 실패 이유를 수정한 뒤 DB 명령을 명시적으로 재실행 | completed 확인 후 소스 감시 재개 |
| 제출이 반려되거나 같은 버전을 다시 쓸 수 없음 | 검토 의견을 반영하고 새 버전 태그 제출. 절차는 App 릴리스하기 참고 | 새 제출 ID와 심사 상태 확인 |
대기 중인 DB 작업을 중복 요청하지 마세요. 요청 응답만 잃었다면 CLI가 출력한 동일 --request-id로 복구합니다. migration 이력이나 데이터를 지워 해결하지 않습니다.
설치·명령 입력 오류
| 오류 문구 또는 증상 | 원인과 해결 | 확인 |
|---|---|---|
Install PHP 8.5.12+ and Composer first / Run nexia setup --devtools | PHP와 Composer 실행 경로를 확인한 뒤 nexia setup --devtools 실행 | 같은 터미널에서 앱 생성 명령 성공 |
Choose a new App directory | 생성 대상에 기존 파일이 있음. 다른 빈 경로를 선택하고 기존 파일은 보존 | 새 앱 폴더에 nexia.json, composer.json 생성 |
--port must be an integer from 1 to 65535 | 주소가 아니라 포트 숫자만 입력: nexia dev --port 9999 | CLI가 해당 포트의 미리보기 URL 출력 |
| 비대화형 실행에서 필수 입력을 요구함 | nexia <명령> --help로 옵션 확인 후 필요한 이름·vendor·family 등을 명시. 승인이 필요한 쓰기는 내용을 확인한 뒤 명시적으로 승인 | 누락된 질문 없이 의도한 대상 표시 |
| 이전 명령을 찾지 못함 | 현재 명령은 nexia --help와 CLI 명령 확인. 예전 명령의 별칭이 있다고 가정하지 않음 | 현재 CLI 도움말에 명령 표시 |
폴더·인증·앱 식별 오류
| 오류 문구 | 원인과 해결 | 확인 |
|---|---|---|
Run nexia connect from the parent project directory, outside an App / Do not nest projects | 앱 안이나 기존 프로젝트 안에서 새 프로젝트를 연결하려 함. 앱의 상위 프로젝트 폴더 또는 기존 프로젝트 바깥의 빈 폴더에서 연결 | nexia status의 프로젝트 일치 |
This folder is already connected to another project | 폴더 연결은 기존 프로젝트를 보호함. 해당 프로젝트를 계속 쓰거나 별도 빈 폴더에 원하는 프로젝트 연결 | Console 프로젝트 ID와 상태의 ID 일치 |
Log in to the project linked to this folder / needs an approved connection / Browser approval expired | 연결된 프로젝트 폴더에서 nexia login --no-browser 실행. 출력 URL을 열어 의도한 프로젝트를 승인 | nexia status에 인증된 프로젝트 표시 |
App binding changed / Runtime state does not match this App binding / different App identity | 실행 중 연결 또는 앱 식별자가 바뀜. dev를 종료하고 원래 폴더·연결을 복구. .nexia 식별자를 임의 편집하거나 지우지 않음. 원래 연결을 복구할 수 없으면 지원 요청 | 원래 프로젝트·앱으로 조회되고 충돌 재발 없음 |
App metadata is incomplete / nexia.json version 2 / extra.nexia is unsupported | nexia.json의 schema_version 2, runtime laravel, 앱 키와 Composer 패키지 이름 확인. App 패키지 만들기에 맞게 소스를 수정 | 앱 폴더에서 nexia check 통과 후 등록 성공 |
Waiting for App / Select an App with --app / at most 20 local Apps | 프로젝트 바로 아래에 앱을 두고 실제 폴더명 또는 앱 키로 nexia dev --app my-app 실행 | 출력 Scope에 의도한 앱 표시 |
로컬 빌드·소스 업로드 오류
| 오류 문구 | 원인과 해결 | 확인 |
|---|---|---|
Frontend dependencies are missing / waiting for frontend dependencies | 대상 앱 폴더에서 npm install. PHP 의존성도 없으면 composer install --no-scripts. 프로젝트 폴더로 돌아와 dev 실행 | Vite 빌드 완료 후 App preparation 시작 |
Frontend build did not finish within two minutes | 바로 위 Vite 출력의 첫 오류 확인. import 경로·설치·빌드 설정을 수정한 뒤 dev 재시작. 빌드가 느린지 실패했는지 먼저 구분 | 프런트엔드 빌드 완료 |
EADDRINUSE | 지정 포트를 이미 사용 중. 내가 실행한 이전 dev를 종료하거나 다른 빈 포트로 실행. 다른 프로세스를 무조건 종료하지 않음 | 새 CLI URL로 미리보기 연결 |
Source changed while reading / waiting for Git to finish | 저장·복제·merge·rebase가 진행 중. Git 작업을 완료하거나 정상 절차로 취소한 뒤 재시도. 잠금 파일을 임의 삭제하지 않음 | 소스 대기 종료 후 준비 시작 |
Unsupported source path / Unsupported source file / Source symlinks are not supported | 표시된 파일의 경로·확장자·심볼릭 링크를 확인. 지원되는 일반 소스 파일로 변경하고 import 참조도 수정 | 해당 경로 오류 없이 소스 업로드 |
Private server code or credentials cannot use this source path | 공개 경로에 PHP 서버 코드나 인증 파일이 포함됨. 비공개 코드는 서버 소스 위치에 두고 인증 파일은 업로드 대상에서 제외 | 비밀값 없이 업로드 성공 |
Source snapshot exceeds 2000 files, 2 MiB per file, or 16 MiB total | 표시된 상한을 초과함. 개발 소스에 섞인 대용량 산출물·미디어를 별도 보관하고 필요한 소스를 줄임. .gitignore만 추가해 제외된다고 가정하지 않음 | 소스 업로드 성공 |
nexia check는 소스 검사입니다. 통과해도 원격 migration, 샌드박스 준비, 실제 저장 성공까지 보장하지 않습니다.
CLI·Core·샌드박스 매니저 버전이 함께 갱신되면 카탈로그 검증 오류를 최대 1,000건까지 invalid, too_long 등의 코드와 함께 보여주고, 나머지 건수도 표시합니다. [PREPARATION_FAILED]의 database access check는 App 코드 실행 전 단계입니다. migrator:connection, runtime:schema_create처럼 역할별 코드로 플랫폼 DB 점검 실패를 구분합니다. 이전 실행 기록에는 단계만 남아 있을 수 있으므로 이 문구만으로 App 결함을 단정하거나 데이터를 초기화하지 마세요.
소스 갱신이 2분 넘게 대기하면 CLI가 작업 ID와 지원 확인 안내를 표시합니다. 원래 ID와 기존 데이터를 유지하세요. 이 안내만으로 갱신 실패를 확정하거나 DB 명령을 반복해서는 안 됩니다.
플랫폼 HTTP·네트워크 오류
| 오류 | 다음 조치 | 확인 |
|---|---|---|
| HTTP 401 | 연결된 프로젝트에서 다시 로그인하고 승인. 토큰을 파일에 직접 붙여 넣지 않음 | nexia status에 승인한 프로젝트가 표시됨 |
| HTTP 403·404 | Console 로그인 계정, 프로젝트 참여 권한, 앱·샌드박스 대상을 확인. 상태 코드만으로 삭제됐다고 판단하지 않음 | 권한 있는 계정으로 해당 프로젝트에 접근 가능 |
| HTTP 409 | 뒤에 표시된 충돌 이유를 읽음. 중복 writer는 다른 dev 종료 후 잠금 해제를 기다리고, 준비·DB 작업 중이면 같은 작업의 상태를 확인. 실행 오류는 아래 절차에 따라 수정 | 기존 작업의 완료 또는 실패 이유 확인 |
| HTTP 422 | 출력된 필드별 검증 오류를 수정. 같은 입력을 반복 전송하지 않음 | 수정한 요청이 입력 검증을 통과함 |
| HTTP 429 | CLI가 표시한 재시도 시간을 기다림. 여러 터미널에서 반복 실행하지 않음 | 재시도 간격 후 같은 작업이 재개됨 |
| HTTP 502·503·504 / timeout / connection reset | 연결과 플랫폼 가용성 확인. 상태 조회는 dev가 자동 재시도할 수 있음. 쓰기 응답이 끊긴 경우 새 요청을 만들기 전에 아래 요청 복구 절차 적용 | 상태 조회가 복구되고 원래 쓰기 요청의 결과가 확인됨 |
Invalid ... response / Platform returned a conflicting ... | 응답이 요청의 대상·식별자와 맞지 않음. 현재 버전과 대상 플랫폼 확인 후 원래 오류·작업 ID로 지원 요청. 로컬 식별자를 응답에 맞춰 덮어쓰지 않음 | 계속하기 전에 응답 식별자가 의도한 작업과 일치함 |
개발을 유지하며 앱 오류 수정하기
nexia dev는 켜 두세요. 터미널과 개발자 콘솔에서 실패 단계와 확인 가능한 앱 파일·줄 번호를 보여줍니다. 오류를 수정하는 동안에도 소스 감시와 업로드는 계속됩니다. 이전 실행이 종료되면 변경한 소스를 관리자 승인 없이 적용합니다.
CATALOG_VALIDATION_FAILED: 표시된 선언을 수정하고nexia check를 실행합니다.SDK_VERSION_MISMATCH: 서버 SDK가 지원하는 API와 의존성 요구 범위를 사용합니다. 새 API가 꼭 필요하면 플랫폼 런타임 업데이트가 필요하며 로컬 의존성 설치로 서버 버전은 바뀌지 않습니다.DATABASE_MIGRATION_REQUIRED:nexia db migrate를 명시적으로 실행합니다.APPLIED_MIGRATION_SOURCE_MISMATCH: 이미 적용한 migration 파일을 원래대로 복원하고 추가 변경은 새 migration으로 작성합니다.MIGRATION_OUTCOME_UNCERTAIN: 일부 적용된 DB 변경을 확인하고 수정합니다. 실패한 DB 명령은 자동으로 반복하지 않습니다.MIGRATION_OWNERSHIP_MISMATCH: 플랫폼에서 DB 할당을 수정해야 합니다. 소스 감시는 유지됩니다.
needs_review는 제출한 앱의 심사 대기에만 사용합니다. 제출 실패 이유를 확인해 소스를 수정하고 새 Git 태그로 다시 제출하세요. 심사 대기나 거절은 개발을 막지 않습니다. nexia recover 명령이나 개발 재개를 위한 관리자 승인 절차는 없습니다. 기존 데이터와 migration 이력은 보존합니다.
DB·제출 요청의 응답을 잃은 경우
먼저 대상 앱 폴더에서 상태를 조회합니다.
nexia db status
nexia submit status <submission-id>- DB 요청:
nexia db migrate·nexia db seed <key>등 원래 실행한 명령에 출력된 동일--request-id <request-id>를 붙여 복구합니다. seed는 같은 fixture key를 유지하세요. 같은 연결의dev는 켜 둡니다. 명령은 완료까지 기다리며 같은 요청 복구는 이후 로컬 수정 사항을 적용하지 않습니다. - 제출 요청: 제출 ID가 있으면 위 status 명령을 우선 사용합니다. 수락 응답을 잃었다면
nexia submit --tag <원래-tag> --request-id <원래-request-id>로 동일 요청을 복구합니다.retryable일 때만nexia submit retry <submission-id>를 사용하고 코드 수정은 새 버전 태그로 제출합니다. - 저장소 연결 대기:
Connection confirmation timed out이면 Console의 앱 저장소 페이지에서 연결 상태를 확인합니다. 저장소 접근 권한과 원격 태그가 준비됐는지 확인한 뒤 제출을 진행하세요. - 앱 준비 요청:
.nexia상태를 유지한 채 같은 폴더에서 dev를 다시 실행하면 저장된 요청을 먼저 조회합니다. 오류를 수정하는 동안에도 소스 감시는 유지됩니다.
진행 중인 요청은 종료 결과를 확인한 뒤 쓰기를 다시 시도하세요. 응답 유실만으로 쓰기가 실패했다고 판단하지 않습니다.
프로젝트가 다르거나 미리보기가 열리지 않는 경우
프로젝트는 앱·권한·연결의 관리 단위이고, 샌드박스는 프로젝트의 앱을 실행하는 임시 환경입니다. 로컬 프로젝트를 연결해도 기존 샌드박스가 다른 프로젝트로 이동하지 않습니다.
nexia status의 프로젝트가 Console과 다르면 올바른 프로젝트 폴더를 사용하세요. 새로 연결할 때는 빈 폴더에서 Console의nexia connect <project-id>명령을 실행합니다.- 다른 프로젝트의 샌드박스가 있다면 **기존 샌드박스 관리 (새 탭)**에서 대상을 확인하세요. 계속 사용할 환경이면 그 프로젝트에서 개발합니다. 교체하려면 필요한 테스트 데이터를 먼저 보관하고 삭제 안내를 확인하세요. 삭제 완료 후 원래 탭을 새로고침하고 현재 프로젝트의 샌드박스를 준비합니다.
- 포트 충돌이면 기존
nexia dev를 Ctrl+C로 종료하고nexia dev --port 9999처럼 빈 포트로 실행하세요. 새로 출력된 URL을 같은 컴퓨터에서 열고 CLI는 실행 상태로 유지합니다. Console에 표시된 로컬 미리보기 주소가 새 포트인지 확인하세요.
복구 확인
nexia status
nexia dev실행 준비가 끝나면 워크스페이스에서 문제가 있던 동작을 다시 수행합니다. 소스 검사 성공만으로 저장이나 권한 문제가 해결됐다고 판단하지 않습니다.
지원 요청
계속 실패하면 개발자 지원에 CLI 버전, OS, 발생 시각, 프로젝트·앱, 재현 순서와 요청 ID를 알려주세요. 토큰·비밀번호·고객 데이터는 제외합니다. 대응하는 Core·SDK·Manager·CLI에서는 카탈로그 오류를 최대 1,000건과 생략 건수로 표시합니다. 개발 준비 중 PHP 예외는 해당 실행에 접근할 수 있는 개발자에게 메시지, 원인 예외, 파일·줄과 스택을 제공합니다. 알려진 런타임 자격 증명, 쿼리 값과 스택 인수는 제외합니다. 메시지·스택은 각각 16 KiB, 스택 64프레임과 원인 예외 8단계까지이며 초과하면 생략 여부를 표시합니다. 이전 실행 기록에는 새 상세 정보가 소급해서 추가되지 않습니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.