본문으로 건너뛰기
문제 해결

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 --devtoolsPHP와 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 9999CLI가 해당 포트의 미리보기 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 unsupportednexia.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·404Console 로그인 계정, 프로젝트 참여 권한, 앱·샌드박스 대상을 확인. 상태 코드만으로 삭제됐다고 판단하지 않음권한 있는 계정으로 해당 프로젝트에 접근 가능
HTTP 409뒤에 표시된 충돌 이유를 읽음. 중복 writer는 다른 dev 종료 후 잠금 해제를 기다리고, 준비·DB 작업 중이면 같은 작업의 상태를 확인. 실행 오류는 아래 절차에 따라 수정기존 작업의 완료 또는 실패 이유 확인
HTTP 422출력된 필드별 검증 오류를 수정. 같은 입력을 반복 전송하지 않음수정한 요청이 입력 검증을 통과함
HTTP 429CLI가 표시한 재시도 시간을 기다림. 여러 터미널에서 반복 실행하지 않음재시도 간격 후 같은 작업이 재개됨
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·제출 요청의 응답을 잃은 경우

먼저 대상 앱 폴더에서 상태를 조회합니다.

코드 예시
Shell
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에 표시된 로컬 미리보기 주소가 새 포트인지 확인하세요.

복구 확인

코드 예시
Shell
nexia status
nexia dev

실행 준비가 끝나면 워크스페이스에서 문제가 있던 동작을 다시 수행합니다. 소스 검사 성공만으로 저장이나 권한 문제가 해결됐다고 판단하지 않습니다.

지원 요청

계속 실패하면 개발자 지원에 CLI 버전, OS, 발생 시각, 프로젝트·앱, 재현 순서와 요청 ID를 알려주세요. 토큰·비밀번호·고객 데이터는 제외합니다. 대응하는 Core·SDK·Manager·CLI에서는 카탈로그 오류를 최대 1,000건과 생략 건수로 표시합니다. 개발 준비 중 PHP 예외는 해당 실행에 접근할 수 있는 개발자에게 메시지, 원인 예외, 파일·줄과 스택을 제공합니다. 알려진 런타임 자격 증명, 쿼리 값과 스택 인수는 제외합니다. 메시지·스택은 각각 16 KiB, 스택 64프레임과 원인 예외 8단계까지이며 초과하면 생략 여부를 표시합니다. 이전 실행 기록에는 새 상세 정보가 소급해서 추가되지 않습니다.

CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.

원본 위치: docs/developers/content/ko/troubleshooting/common-installation-errors.md