json-render UI 생성 오류가 발생하면 어떻게 해결할까? 2026 React 장애 대응 가이드

화면이 갑자기 빈 페이지가 되거나 버튼 일부만 나타난다면, 모델을 다시 호출하기 전에 원시 출력과 UI 명세부터 보존해야 합니다.

가장 안전한 해결 순서는 생성 프로토콜, Schema 검증, 컴포넌트 목록, 스트리밍 상태, 업무 권한을 차례로 점검하는 것입니다. 검증할 수 없는 UI는 등록되지 않은 컴포넌트나 액션을 실행하지 말고 구조화된 텍스트 또는 고정 컴포넌트로 낮춰야 합니다.

이 글은 json-render 데모를 실제 React 앱으로 확장하는 프런트엔드 개발자를 위한 글입니다. JSON Schema와 컴포넌트 허용 목록을 관리하는 AI 앱 엔지니어, 원격 빌드 환경이나 클라우드 에이전트에서 UI를 생성하고 배포하는 플랫폼 팀도 대상입니다.

먼저 고장 난 층위 확인

최종 화면만 보면 같은 빈 화면이라도 원인이 달라집니다. 다음처럼 증상을 먼저 분류하면 불필요한 모델 재호출을 줄일 수 있습니다.

• 완전한 빈 화면: JSON 파싱, 루트 명세, React 렌더링 예외를 먼저 봅니다.
• 일부 컴포넌트만 표시: 등록되지 않은 이름, 속성 매핑 오류, 중첩 구조의 잘림을 확인합니다.
• Schema 검증 실패: 필수 속성, 자료형, 배열 구조, 닫히지 않은 객체를 대조합니다.
• 버튼이나 액션이 반응하지 않음: 이벤트 연결, 액션 허용 목록, 서버 권한 검사를 분리해서 확인합니다.
• 내용이 다른 사용자에게 노출됨: 모델 응답이 아니라 데이터 범위와 서버 인가 검사를 우선 의심해야 합니다.

장애가 발생하면 다음 세 가지를 같은 요청 식별자로 묶어 저장합니다.

• 모델이 반환한 원시 텍스트
• 파싱 이후의 UI 명세
• 브라우저와 서버의 React 오류, 검증 오류, 네트워크 오류

json-render가 JSON 명세와 미리 정의된 컴포넌트를 바탕으로 React 화면을 만든다는 구조는 공식 문서의 기본 렌더링 설명에서 확인할 수 있습니다. 따라서 최종 화면의 모양보다 명세가 어느 단계에서 바뀌었는지를 추적하는 편이 빠릅니다.

생성 계약과 Schema 검증

불완전한 JSON 분리

생성 결과가 JSON처럼 보인다고 바로 렌더링해서는 안 됩니다. 코드 블록 표시, 앞뒤 설명 문장, 닫히지 않은 배열, 잘못된 따옴표가 남아 있으면 파싱 단계에서 실패합니다. 파싱 전에 문자열을 억지로 잘라내면 오류 원인이 사라지므로 원본을 보존한 뒤 별도의 정규화 결과를 기록해야 합니다.

검증 순서는 다음과 같이 고정하는 것이 좋습니다.

• 루트 자료형이 예상한 객체인지 확인합니다.
• 필수 속성이 모두 있는지 확인합니다.
• 문자열, 배열, 불리언 등 각 속성의 자료형을 확인합니다.
• 중첩 객체와 배열 안의 항목까지 검사합니다.
• 컴포넌트 이름과 액션 이름이 허용 목록에 있는지 확인합니다.

JSON Schema 객체 규칙을 기준으로 필수 속성과 추가 속성 허용 여부를 명시하면, 개발 환경에서는 통과하지만 운영 환경에서 깨지는 차이를 줄일 수 있습니다.

처리 방식 선택

Schema 오류에는 세 가지 대응이 있습니다.

• 엄격한 거부: 결제, 저장, 외부 호출처럼 부작용이 있는 화면에 적합합니다. 검증 실패 즉시 고정 오류 화면으로 전환합니다.
• 제한적 자동 수정: 공백 제거, 누락된 선택형 기본값 보완처럼 의미가 바뀌지 않는 경우에만 사용합니다.
• 재생성: 오류 경로와 허용된 구조만 모델에 전달해 다시 생성합니다. 원래 입력과 첫 번째 실패 결과는 삭제하지 않습니다.

자동 수정이 성공해도 권한 검사를 생략할 수는 없습니다. 형식이 유효하다는 사실은 해당 사용자가 그 데이터를 보거나 액션을 실행할 권리가 있다는 뜻이 아니기 때문입니다.

컴포넌트 목록과 속성 매핑

json-render 컴포넌트가 나타나지 않는 문제는 모델의 추론 실패보다 프런트엔드 등록 상태의 불일치에서 자주 시작됩니다. 공식 컴포넌트 문서의 등록 방식과 속성 구조를 기준으로 다음 항목을 비교합니다.

• 모델이 생성한 컴포넌트 이름과 실제 등록 키가 같은지 확인합니다.
• 속성 이름과 자료형이 현재 React 컴포넌트의 입력 규격과 맞는지 확인합니다.
• 이벤트 이름이 단순 문자열인지, 허용된 액션 식별자인지 구분합니다.
• 업데이트된 컴포넌트와 이전 버전의 기본값이 달라지지 않았는지 확인합니다.
• 같은 이름을 가진 컴포넌트가 여러 디렉터리에 중복 등록되지 않았는지 확인합니다.
• HTML 삽입, 임의 스크립트, 제한 없는 URL처럼 위험한 속성을 차단합니다.

모델이 알 수 없는 컴포넌트를 생성했을 때 임의의 React 컴포넌트로 연결하는 방식은 피해야 합니다. 알 수 없는 이름은 오류 로그에 남기고, 제목·설명·목록 같은 구조화된 텍스트로 대체하는 편이 안전합니다. 자유로운 코드 생성과 허용된 명세 렌더링을 한 체인에 섞으면 컴포넌트 허용 목록이 사실상 무력화됩니다.

스트리밍 상태와 JSONL 패치

스트리밍 화면은 완성된 JSON 하나를 받는 방식과 다릅니다. json-render의 스트리밍 명세 업데이트 방식은 들어오는 변경을 화면 상태에 반영하므로, 패치 순서와 연결 종료 상태를 별도로 관리해야 합니다.

다음 조건을 로그에 남깁니다.

• 패치 순번
• 대상 경로
• 수신 시각
• 현재 명세의 해시
• 적용 성공 또는 실패 결과
• 연결 종료 사유
• 마지막으로 확인된 완료 상태

JSONL 패치가 뒤섞였는지 확인할 때는 패치 순번이 이전 값보다 작아졌는지, 같은 경로에 같은 변경이 반복되었는지, 한 연결에서 동일한 식별자가 두 번 적용되었는지를 검사합니다. 경로 변경의 의미는 JSON Patch 표준과 애플리케이션의 패치 계약을 함께 기준으로 삼아야 합니다.

서버 전송 이벤트를 사용한다면 연결 재개와 종료 처리를 애플리케이션에서 명시해야 합니다. 브라우저의 서버 전송 이벤트 동작을 참고해 중단된 연결을 정상 완료로 오인하지 않도록 합니다.

불완전한 명세에는 다음 상태 중 하나를 부여합니다.

• 로딩 중: 표시 전용 자리표시자만 렌더링합니다.
• 검증 대기: 입력과 액션을 비활성화합니다.
• 완료: 최종 Schema와 권한 검사를 통과한 경우에만 상호작용을 허용합니다.
• 복구 필요: 서버에서 완성 명세를 다시 가져오거나 고정 화면으로 전환합니다.

자리표시자 상태에서 저장, 삭제, 외부 요청이 실행되면 반쪽짜리 화면 문제가 업무 데이터 변경으로 번질 수 있습니다.

주의: 스트리밍이 끝났다는 네트워크 신호와 UI 명세가 안전하다는 판단은 서로 다릅니다. 연결이 정상 종료되어도 최종 Schema와 액션 권한을 다시 확인해야 합니다.

액션 권한과 데이터 범위

합법적인 JSON도 위험할 수 있습니다. 화면에 표시할 제목과 사용자의 데이터를 변경하는 액션은 같은 방식으로 허용해서는 안 됩니다.

권한을 다음처럼 나누면 경계가 분명해집니다.

• 표시 컴포넌트: 읽을 수 있는 데이터만 전달합니다.
• 입력 컴포넌트: 형식과 길이를 검증하고 서버에서 다시 확인합니다.
• 액션 컴포넌트: 액션 이름, 대상 식별자, 매개변수, 사용자 권한을 모두 검증합니다.
• 외부 호출 컴포넌트: 허용된 대상과 요청 범위를 고정합니다.

권한 검사는 브라우저가 아니라 서버에서 수행해야 합니다. 사용자가 볼 수 있는 데이터 범위와 변경할 수 있는 데이터 범위가 다를 수 있기 때문입니다. OWASP 권한 부여 지침은 요청마다 권한을 확인하고, 기본값을 거부하며, 권한 판단을 감사 가능한 기록으로 남기는 방향을 제시합니다.

복구 경로와 회귀 기록

오류마다 같은 복구 방법을 적용하면 안 됩니다. 다음 조건으로 결정하면 운영 중 판단이 일관됩니다.

• Schema가 깨졌고 읽기 전용 화면이라면 제한적 자동 수정을 시도합니다. 수정 뒤에도 실패하면 고정 템플릿으로 전환합니다.
• 등록되지 않은 컴포넌트라면 실행하지 않고 구조화된 텍스트로 대체합니다.
• 패치 순서가 불명확하거나 연결이 끊겼다면 현재 화면의 액션을 잠그고 완성 명세를 다시 요청합니다.
• 액션 권한이 확인되지 않는다면 입력값을 보존하되 실행하지 않고 사용자 확인 또는 운영자 검토로 보냅니다.
• 같은 요청이 연속 실패한다면 원시 입력, 명세, 오류 경로를 보존한 뒤 고정 화면으로 회귀합니다.

복구가 끝나면 다음 회귀 사례를 테스트에 추가합니다.

• 필수 속성이 빠진 명세
• 존재하지 않는 컴포넌트 이름
• 동일 패치의 중복 적용
• 순서가 바뀐 패치
• 중간 연결 종료
• 권한이 없는 데이터 요청
• 허용되지 않은 액션 매개변수
• 자동 수정 뒤에도 남은 위험한 속성

배포 전에는 요청 식별자, 사용자 권한 범위, 원시 출력 위치, 파싱 결과, Schema 오류 경로, 컴포넌트 등록 버전, 패치 순번, 복구 단계, 액션 거부 이유를 하나의 추적 단위로 연결해야 합니다. 이 기록이 있어야 한 번의 장애가 다음 회귀 테스트로 바뀝니다.

장애 기록을 남기는 기준

마지막으로 다음 확인 목록을 코드 리뷰와 운영 점검에 함께 사용합니다.

• [ ] 원시 모델 출력과 파싱 결과가 분리되어 보존됩니다.
• [ ] Schema 오류가 필드와 경로 단위로 기록됩니다.
• [ ] 컴포넌트 허용 목록이 배포 버전과 함께 관리됩니다.
• [ ] 미등록 컴포넌트와 위험한 속성이 차단됩니다.
• [ ] JSONL 패치에 순번과 대상 경로가 있습니다.
• [ ] 불완전한 명세에서는 입력과 액션이 잠깁니다.
• [ ] 서버가 사용자 권한과 데이터 범위를 다시 검사합니다.
• [ ] 고정 컴포넌트와 구조화된 텍스트 대체 화면이 준비되어 있습니다.
• [ ] 연속 실패 시 재시도에 필요한 원본이 남습니다.
• [ ] 각 장애가 회귀 테스트 사례로 등록됩니다.

이 과정을 원격 빌드나 클라우드 개발 환경에 적용할 때는 로그 수집, 재현용 저장소, 롤백 권한을 먼저 분리해야 합니다. 원격 환경에서 생성된 UI를 바로 운영 브랜치에 병합하지 않고, Zutcloud의 도움말 센터에서 관련 운영 절차를 확인한 뒤 검증 환경과 배포 환경을 나누는 방식이 적합합니다.

자주 묻는 문제

json-render를 사용하는 React 팀에서 장애를 빠르게 줄이는 방법은 모델을 더 자주 재호출하는 것이 아닙니다. 원시 출력부터 렌더링 오류까지의 경로를 기록하고, 검증할 수 없는 결과를 실행하지 않는 것입니다.

현재 방식이 로컬 장비에만 의존하면 재현 환경이 팀원마다 달라지고, 원격 에이전트가 만든 변경을 되돌리거나 같은 명세로 다시 테스트하기도 어렵습니다. 반대로 클라우드 개발 환경은 권한, 로그, 저장소, 롤백 정책을 함께 설계해야 하므로 단순히 환경을 빌리는 것만으로 문제가 해결되지는 않습니다. 다만 일시적인 React 빌드 검증, 여러 명세의 회귀 실행, 원격 AI 앱 테스트가 목적이라면 Zutcloud의 맥 미니 렌탈 환경을 활용해 고정된 테스트 절차를 마련하는 편이 실무적으로 더 나은 선택일 수 있습니다. 장기간 고정 부하를 직접 운영하거나 물리 장치 연결이 필수라면 자체 장비가 더 적합합니다.

FAQ

json-render Schema 검증이 실패했을 때 가장 먼저 확인할 부분은 무엇인가요?

먼저 모델 응답이 완전한 JSON인지 확인한 뒤, 파싱된 UI 명세를 별도로 저장해야 합니다. 필수 속성 누락, 잘못된 자료형, 닫히지 않은 중첩 객체를 JSON Schema와 대조합니다. 자동 수정은 표시용 형식을 보완하는 데만 사용하고, 권한이나 실행 조건을 우회하는 수단으로 사용하면 안 됩니다.

json-render 컴포넌트가 화면에 나타나지 않을 때 어떻게 진단하나요?

모델이 생성한 이름이 실제 등록 목록에 있는지, 속성 이름과 이벤트 연결 방식이 현재 React 컴포넌트 버전과 맞는지 확인합니다. 등록되지 않은 이름은 임의로 실행하지 말고 구조화된 텍스트나 고정 컴포넌트로 바꿉니다. 같은 이름의 컴포넌트가 여러 버전에 존재하는 경우에는 등록 목록에 버전 정보를 함께 기록하는 편이 안전합니다.

LLM-to-UI 스트리밍 JSONL 패치가 뒤섞였는지 어떻게 판별하나요?

각 패치에 순번과 대상 경로를 기록하고, 같은 패치가 두 번 적용되었는지 확인합니다. 연결이 끊긴 뒤 마지막으로 받은 순번이 서버의 종료 상태와 일치하지 않으면 화면을 완료된 상태로 취급하지 않아야 합니다. 서버에서 완성된 명세를 다시 받아 비교하면 순서 오류와 중단 오류를 구분할 수 있습니다.

AI가 만든 UI를 고정 컴포넌트로 안전하게 낮추려면 어떻게 해야 하나요?

표시용 컴포넌트와 입력용 컴포넌트, 외부 호출이나 데이터 변경을 일으키는 액션 컴포넌트를 먼저 분리합니다. 검증에 실패한 명세는 고정된 안내 화면으로 보내고, 액션은 서버 권한 검사를 통과한 뒤에만 활성화합니다. 반복 실패 시에는 원래 입력과 오류 기록을 보존해 재시도와 수동 검토가 가능해야 합니다.

더 읽기

• 함수 호출의 기본 흐름과 오류 점검법 알아보기
• 에이피아이와 데이터베이스 도구를 연결할 때 검증 순서 살펴보기
• 명세 중심 개발로 인공지능 화면의 구조와 검증 기준 세우기