공식 TROUBLESHOOTING.md는 "증상 → 수정법 하나" 구조입니다. 여기서 뽑은 것도 같은 방식으로 읽으세요. 설치는 앱/터미널, 소스 체크아웃 중 어떤 경로로 했는지부터 확정하는 게 첫 단계입니다.

해결 전, 이것부터 확인하세요

문제가 발생했을 때 가장 먼저 다음 세 가지 명령어로 현재 상태를 점검해 보세요. 버그 리포트를 작성하실 때 이 출력 결과들을 함께 첨부해 주시면 훨씬 빠른 도움을 받으실 수 있습니다.

strata --version
strata doctor --live     # 설치된 엔진 파일과 인식된 그래픽 카드를 비교합니다 (읽기 전용)
strata launch --status   # 현재 어떤 모델이 서빙 중인지 확인합니다

설치가 정상적으로 되었는지는 strata launch --status의 결과와 /health 엔드포인트의 응답으로 판별할 수 있습니다.

설치 후 명령어가 인식되지 않을 때

• Windows: 설치 완료 후 새 PowerShell 창을 열어 PATH 설정을 갱신해 주세요.
• Linux/Mac: 설치기가 안내한 전체 경로(보통 ~/.local/bin/strata)를 직접 입력하거나, ~/.local/bin 폴더를 PATH 환경 변수에 추가하세요. strata --version이 정상적으로 출력되는지 확인합니다.
• 앱 설치 후 START-HERE.bat/SETUP.bat 파일을 찾으시는 경우: 해당 파일들은 소스 저장소(Git Checkout) 전용입니다. 설치형 앱을 사용하신다면 앱 실행 또는 strata launch 명령어가 시작 지점입니다.

'이 컴퓨터용 엔진을 찾을 수 없다' 경고

엔진은 그래픽 카드와 대화하는 부분입니다. Strata는 거부하지 않고 경고한 뒤 모델을 계속 다운로드하지만, 맞는 엔진이 생기기 전까지 모델이 안 돌아갈 수 있습니다. 흔한 원인:

• 엔진이 아직 없고 릴리스에 이 카드용이 없다
• 다른 제조사 카드를 위한 엔진이 잡혔다
• 그래픽 드라이버가 너무 낡았다

처리: 앱에서는 설정 → Engine에서 Update engine, 터미널에서는 strata update --check 후 strata update. strata doctor --live로 선택된 GPU·드라이버를 확인하고 백엔드 가이드를 보세요. NVIDIA·AMD discrete가 없다고 미지원이 아닙니다(Apple Silicon, Linux의 Intel Arc는 지원 경로). 반대로 내장 Intel UHD/Iris뿐이거나 가상 머신·Windows on ARM이면 Strata가 그렇게 뜨고 설치할 게 없습니다.

모델이 더 새 엔진을 요구할 때

Gyro는 0.1.45.1+, NVFP4는 0.1.44+, NVFP4-QAD는 0.1.45.1+ 등 모델별 최소 엔진이 다릅니다. 앱은 'Update engine' 버튼을, 터미널은 strata update를 쓰면 되고, 새 엔진은 시험 시작 통과 후에만 적용됩니다. 최신 엔진이는데도 메시지가 남는다면 릴리스에 이 조합이 아직 없는 것이니 missing 조합으로 리포트하세요. 업데이트 성공 후 strata --version이 그대로면 다음 명령에서 반영되는 것(터미널은 다음 실행부터 새 Control 사용). 그래도 그대로면 Installer를 한 번 더 돌립니다(모델·설정 유지).

첫 실행에 PC가 멈추거나 느려진다

첫 시작은 정상 현상입니다. 엔진이 35~55GB를 RAM에 올리고 일부는 그래픽 카드를 위해 잠그고, 모델의 어디까지 카드에 들어가는지 계산합니다. 마우스가 몇 분 멈출 수 있습니다. 창을 닫지 말고 기다리세요. 두 번째 실행부터는 파일이 OS 캐시에 남아 훨씬 빠릅니다. 10분이 지나도 그러면 재시작 후 다른 프로그램(브라우저가 RAM을 많이 씁니다)을 끄고, 계속되면 더 작은 크기(Q2_0·IQ2_XS)를 고릅니다.

Linux에서 엔진은 커널에 모델 파일 선행 읽기를 요청합니다(한 PC에서 첫 시작 ~920초 → 70초). 끄려면 STRATA_READ_AHEAD=0.

엔진이 로그 없이 죽고 killed by signal 4 (SIGILL)/0xC000001D가 보이면 CPU가 명령어를 실행하지 못하는 것입니다. 에러에 나열된 AVX2·FMA·F16C 등 누수 플래그와 CPU 정보를 함께 적어 리포트하세요.

포트 충돌과 재시작

• 먼저 strata launch --status로 이미 Strata가 도는지 확인.
• 기존 실행을 교체하려면 --restart(진행 중 답변은 중단). 나란히 두려면 --port 8081 등 다른 포트(메모리 허용 시).
• 정말 사용 중인 주소만 "already in use"입니다. 그 외 원인(Windows의 예약 포트, "host"가 이 PC 주소가 아님)은 OS 메시지를 그대로 띄웁니다. Port를 점유한 무관한 프로그램을 함부로 끄지 마세요.
• --yes만으로는 실행 중 모델을 재시작하지 않습니다.

Mac에서 '확인할 수 없는 개발자' 경고가 뜰 때

Apple Silicon용 파일과 macOS 15 이상인지 먼저 확인. 공식 릴리스는 공증을 받으므로, Applications로 드래그한 뒤 처음 실행 때 "열겠습니까?"가 뜨면 Open을 누르면 됩니다. 비공식 테스트 빌드가 "손상됨"으로 뜨는 경우 휴지통으로 보내지 말고 quarantine 플래그를 제거하세요(공식 릴리스 파일에만):

xattr -dr com.apple.quarantine ~/Downloads/<dmg 파일>      # 열기 전 dmg
xattr -dr com.apple.quarantine /Applications/Strata.app    # 설치 후 앱

spctl -a -vv /Applications/Strata.app가 "accepted / Notarized Developer ID"를 돌려주면 공증된 판입니다. curl ... | sh 설치는 플래그가 없어 이 작업이 필요 없습니다.

이미지 판독이 거부되거나 느리다

• "this server was started without the vision encoder": 텍스트 전용으로 설정된 서버입니다. 앱이나 launch의 Pictures 단계에서 켜거나 --vision on|gpu|cpu로 지정하세요.
• 몇 초씩 걸리면 CPU 판독기입니다(8코어, 300 이미지 토큰 기준 약 3초). --vision gpu는 VRAM 약 1.4GB를 쓰고 0.1~0.5초로 줄입니다.
• AMD에서 GPU 판독기(strata-vision-hip) 시작 실패 시 "pictures are read on the CPU" 로그 후 계속 동작합니다. Mac은 --vision cpu가 약 50초/이미지. Intel Arc는 CPU가 기본.

기타 자주 나오는 항목들

• Windows Smart App Control이 엔진을 막는다(깨끗한 Windows 11): strata.exe, strata-vision.exe는 아직 서명 전입니다(#735). Smart App Control을 끄는 방법 말고, 판독기만 막혔다면 strata launch --vision off로 텍스트 요청만 쓰는 선택지가 있습니다.
• 수동으로 고친 strata-<model>.json이 되돌아간다: 앱이 관리하지 않는 옵션은 user_args(매 시작마다 우선)에 넣어야 유지됩니다. 앱 Expert settings의 값도 여기 저장됩니다. 컨텍스트·KV 형식·이미지·초안 레이어는 앱이 직접 고르는 값이라 Models 화면이나 launch 플래그로 바꿔야 합니다.
• VRAM 예약이 과도하게 남는다: 데스크톱 화면을 그리는 카드는 자동 예약(≤16GB 1536MiB, 그 이상 1024MiB, GPU 판독기 시 2048MiB 등)이 생깁니다. 명시적 값은 절대 안 바꿉니다 — Expert settings의 "GPU memory for other apps" 또는 --vram-reserve-mib를 쓰세요.
• Linux AppImage 미실행: 실행 권한 + FUSE2(libfuse2/libfuse2t64) 또는 --appimage-extract-and-run.
• 엔진 checksum 불일치: 파일 손상이나 변경 가능성을 의미하므로 setup이 삭제하고 중단합니다. 다시 받아야 합니다(오프라인이면 체크 생략 경고 후 설치).

개인정보와 네트워크 동작 요약

SAFETY.md의 "At a glance"를 줄이면:

• 채팅·프롬프트·파일·이미지·모델은 PC에 머뭅니다. 나가는 건 사용자가 정한 경우(외부 모델 서비스 추가, 서버를 다른 기기에 개방, 에이전트의 웹 검색)뿐.
• 텔레메트리가 없습니다. 계정·분석·크래시 전송이 코드 어디에도 없습니다(앱 개인정보 노트: "Strata sends no usage telemetry").
• 모델 다운로드 이후 시작·서빙은 인터넷 불필요. 예외는 strata launch가 서명된 feed에 새 DeepSeek 엔진이 있으면 자동으로 갱신하는 경우뿐(연결 없으면 10초 내 포기하고 진행).
• 다운로드는 검증됩니다. 업데이트는 서명된 feed, 모델 파일은 고정 SHA-256과 크기, pinned 버전이 사라지면 설치는 멈춥니다.
• 서버는 기본적으로 이 컴퓨터만 듣습니다. 다른 기기에서 쓰려면 API 키가 필요합니다.

그래도 해결이 안 되면 GitHub 이슈에 strata --version, strata doctor --live, strata launch --status 출력과 정확한 메시지 원문을 함께 적어 리포트하세요.