렌더링 및 I/O 오류

범위

이 항목들은 HTML 파이프라인이 콘텐츠를 레이아웃하고, 페이지 미디어 리졸버가 페이지 기하를 할당하고, 텍스트 셰이퍼가 복잡한 스크립트를 처리하고, 타이포그래피 단계가 줄을 나누고, 라이터가 문서를 직렬화하고, 리더가 기존 PDF를 파싱하고, 메타데이터 단계가 Extensible Metadata Platform(XMP) 패킷을 읽는 동안 발생하는 렌더링 및 입출력(I/O) 예외를 다룹니다.

아래에는 두 가지 기반 계층이 등장하며, 그 차이는 catch 이후 어떤 진단 데이터를 읽을 수 있는지를 결정합니다.

NextPdfException은 ContextAwareExceptionInterface::getContext(): array를 구현합니다. 기반 구현은 빈 배열을 반환합니다. 서브클래스는 getContext()를 재정의할 때만 구조화된 키를 담습니다. 재정의하지 않는 서브클래스도 여전히 public readonly 속성을 통해 데이터를 노출합니다.
여기 있는 몇몇 클래스는 PHP의 RuntimeException을 직접 확장합니다. 이들은 컨텍스트 인식형이 아니며 getContext() 메서드가 없습니다. 대신 getMessage()와 public 속성을 읽으십시오.

각 항목은 정확한 클래스, 트리거 조건, 담는 컨텍스트 키 또는 public 속성, 그리고 복구 경로를 명시합니다.

HTML 레이아웃 및 페이지 미디어

`UnsplittableContentException`

발생 시점. break-inside: avoid로 표시된 콘텐츠(중단 제약이 Avoid인 표 셀)의 측정 높이가 단일 페이지의 사용 가능한 높이를 초과할 때 HTML 레이아웃 엔진이 이를 발생시킵니다. 엔진은 중단 회피 제약과 페이지 경계를 둘 다 충족할 수 없으므로, 조용히 넘치게 두는 대신 실패합니다.
담는 데이터. NextPdfException을 확장하지만 getContext()를 재정의하지 않으므로 getContext()는 빈 배열을 반환합니다. 진단 데이터는 public readonly 속성에 있습니다. gridRow(int), gridCol(int), contentHeight(float, 포인트), pageHeight(float, 포인트)입니다. 메시지는 셀 좌표와 두 높이를 명시합니다.
복구. 문제가 된 셀의 break-inside: avoid 제약을 제거하거나, 셀 콘텐츠를 한 페이지에 들어갈 만큼 줄이거나, 페이지 크기를 키우거나 여백을 줄여 사용 가능한 높이가 콘텐츠를 수용하도록 하십시오.

`BudgetExceededException`

발생 시점. 아키텍처 결정 기록 ADR-020에 정의된 네 가지 리소스 예산 등급 중 하나가 위반되고 호출자가 소프트 폴백 대신 강한 실패를 선택했을 때, 유지(retained) 모드 레이아웃 프리미티브가 이를 발생시킵니다. 기본 경로는 발생하지 않습니다. ContainerLayout::acceptChild()가 false를 반환하고, 호출자는 블록 레이아웃으로 폴백하며, 경고가 발생합니다. 이 예외는 구성 시점 검증과 정확한 위반 튜플을 단언하는 테스트를 위해 예약되어 있습니다. 등급은 per-child(캡처된 자식 스트림이 한도를 초과), per-container(Tier 1 노드 수 예산), per-document(레이아웃 패스 또는 중첩 깊이 예산), global(SDK 전반의 256 MB 피크 상주 집합 크기 한도)입니다.
담는 데이터. getContext()를 재정의하며, application performance monitoring(APM) 도구가 소비하는 안정적인 8-키 형태를 반환합니다. budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize, processedItemCount입니다. 처음 네 키는 원래의 v1.0.0 하위 집합이며 항상 채워집니다. 나머지 네 키는 생성자가 이들 없이 호출될 때 null 또는 0을 기본값으로 둡니다. getCausalWarningCode()는 (등급, 컨테이너 타입) 튜플을 소프트 폴백 경로가 발생시켰을 WarningCode로 매핑합니다.
복구. 구성 위반의 경우, 요청한 값을 문서화된 범위로 다시 낮추십시오(예: 유지 노드 예산은 Config::withRetainedNodeBudget()을 통해 5,000에서 100,000까지 허용). 콘텐츠 위반의 경우, 컨테이너 중첩이나 노드 수를 줄이거나, 강한 실패 표면을 선택하는 대신 블록 레이아웃으로의 기본 소프트 폴백에 의존하십시오.

`UnsupportedNamedPageException`

발생 시점. 문서가 (콘텐츠에 page: <ident> 속성으로 바인딩된) 이름 있는 @page <ident> { … } 규칙을 선언할 때, 페이지 미디어 단계가 fail-closed로 이를 발생시킵니다. CSS Paged Media Level 3 §3.4와 Level 4 §3.2의 이름 있는 페이지(:first, :left, :right, :blank 의사 클래스와 이름 있는 size: 및 rotate: 재정의 포함)는 파싱되지만 어떤 프로덕션 레이아웃 경로도 이를 소비하지 않습니다. 엔진은 규칙을 버려서 발생할 조용히 잘못된 기본 페이지 분할을 내보내는 대신 거부합니다.
담는 데이터. getContext()를 재정의하며, page_names(실패를 트리거한 고유 식별자 목록, 소스 순서), has_size_override(bool), has_rotate_override(bool), has_pseudo_classes(bool)를 반환합니다. 동일한 값이 pageNames, hasSizeOverride, hasRotateOverride, hasPseudoClasses public 속성에 노출됩니다.
복구. 이름 있는 @page <ident> 규칙과 모든 page: <ident> 바인딩을 제거하고, 지원되는 이름 없는 @page { … } 규칙과 그 의사 클래스 형식으로 의도한 기하를 표현하십시오. 또는 완전한 이름 있는 페이지 레이아웃 지원이 도입되는 향후 릴리스에 고정하십시오.

타이포그래피 및 텍스트 셰이핑

`IcuRequirementException`

발생 시점. 텍스트 분절이 International Components for Unicode(ICU) 줄바꿈 반복자를 필요로 하지만, require-ICU 정책이 활성화된(NEXTPDF_REQUIRE_ICU=1) 상태에서 ext-intl 확장과 IntlBreakIterator를 사용할 수 없을 때 발생합니다.
담는 데이터. RuntimeException을 직접 확장하므로 컨텍스트 인식형이 아니며 getContext()가 없습니다. 동일한 코드 경로가 이전에 발생시키던 일반 예외를 엄격하게 정제한 것이므로, 기존 catch (\RuntimeException) 핸들러는 계속 작동합니다.
복구. ext-intl을 설치하고 활성화하여 ICU 줄바꿈 반복자를 사용할 수 있게 하거나, require-ICU 정책이 필수가 아닌 곳에서 비ICU 분절기로 폴백하도록 NEXTPDF_REQUIRE_ICU를 해제하십시오.

`ScriptShaperException`

발생 시점. 이는 스크립트 셰이핑 서비스 제공자 인터페이스(SPI)의 기반 예외입니다. 오늘날 직접 발생하지 않으며, 대신 구체 서브타입이 발생합니다. 모든 셰이핑 실패를 한곳에서 처리하려면 이 타입을 잡으십시오.
담는 데이터. RuntimeException을 직접 확장합니다. 컨텍스트 인식형이 아니며 getContext()가 없습니다.
복구. 구체 서브타입으로 분기하십시오. 현재 릴리스에 출시된 유일한 서브타입은 아래 NotYetImplementedException을 참조하십시오.

`NotYetImplementedException`

발생 시점. 모든 자리표시자 스크립트 셰이퍼는 구체 셰이핑이 연기된 스크립트(몽골 문자와 티베트 문자)에 대해 자신의 shape() 본문에서 이를 발생시킵니다. 셰이핑 SPI 이음새는 아키텍처적으로 준비되어 있지만, 실제 셰이핑은 원어민이 검증한 픽스처를 기다리고 있습니다. 조용한 무동작 대신 예외를 발생시키는 것은, 태깅된 접근성을 표방하는 PDF에 셰이핑되지 않은 텍스트를 내보내는 대신 우발적인 프로덕션 연결을 런타임에 드러냅니다.
담는 데이터. ScriptShaperException(따라서 RuntimeException)을 확장하므로 컨텍스트 인식형이 아니며 getContext()가 없습니다. 진단 데이터는 public readonly 속성에 있습니다. bcp47LanguageTag(런의 BCP-47 태그, 예: mn-Mong 또는 bo-Tibt)와 missingCapability(구현이 결여한 구체 기능)입니다. 메시지는 둘 다 포함합니다.
복구. 미구현 스크립트의 런을 프로덕션에서 셰이퍼로 라우팅하지 마십시오. 상류에서 언어 태그를 감지하여 다른 렌더링 경로로 폴백하거나, 해당 스크립트의 셰이핑이 도입되는 향후 릴리스에 고정하십시오.

라이터 출력 프로파일 및 암호화

`Pdf14FeatureRejectedException`

발생 시점. 문서가 PDF 1.4 출력 프로파일(ISO 19005-1:2005 / PDF/A-1)에서 금지된 기능을 포함할 때 라이터가 이를 발생시킵니다. 이 프로파일은 이후 PDF 버전에서 도입된 구조를 금지합니다.
담는 데이터. NextPdfException을 확장하지만 getContext()를 재정의하지 않으므로 getContext()는 빈 배열을 반환합니다. 진단 데이터는 public readonly 속성에 있습니다. feature(거부된 기능 이름), reason(금지된 이유), isoClause(ISO 절 참조)입니다. 메시지는 셋을 결합합니다.
복구. 거부된 기능을 PDF 1.4 호환 등가물로 제거하거나 대체하거나, 그 기능을 허용하는 상위 출력 프로파일을 대상으로 하십시오.

`Pdf20FeatureRejectedException`

발생 시점. 문서가 엄격한 PDF 2.0 출력 프로파일에서 금지된 기능을 포함할 때 라이터가 이를 발생시킵니다. ISO 32000-2:2020은 PDF 1.7이 여전히 허용하던 구조를 폐기합니다. 가장 두드러진 것은 Standard 14 Type 1 폰트(§9.6.2)로, 적합한 PDF 2.0 문서에서는 반드시 임베드되어야 합니다.
담는 데이터. Pdf14FeatureRejectedException과 동일한 형태입니다. NextPdfException을 확장하고, getContext()를 재정의하지 않으며(빈 배열 반환), feature, reason, isoClause를 public readonly 속성으로 노출합니다.
복구. 거부된 기능을 시정하거나(예: base 14 폰트 임베드), 존재하는 경우 문서화된 탈출구를 사용하십시오(임베드되지 않은 base 14 폰트의 경우 Document::allowNonEmbeddedBase14()).

`PublicKeyEncryptionUnsupportedException`

발생 시점. 라이터 측 공개 키 스트림 본문 암호화 디스패치가 연결되기 전에, 문서의 encryptionMode가 pubkey(공개 키 수신자 목록)일 때 PdfWriter::build()가 진입점에서 이를 발생시킵니다. 사전에 거부하면 호출자가 암호화되었다고 믿는 PDF를 암호화되지 않은 채 조용히 내보내는 것을 방지합니다.
담는 데이터. RuntimeException을 직접 확장하므로 컨텍스트 인식형이 아니며 getContext()가 없습니다. 동일한 지점이 이전에 발생시키던 일반 예외를 엄격하게 정제한 것이므로, 기존 catch (\RuntimeException) 핸들러는 계속 작동합니다.
복구. 공개 키 수신자 목록 대신 지원되는 암호화 모드(비밀번호 기반 암호화)를 사용하거나, 공개 키 암호화 지원이 도입되는 릴리스에 고정하십시오. 이것이 발생할 때 출력을 암호화된 것으로 취급하지 마십시오.

리더 및 메타데이터 입력

`UnsupportedPdfStructureException`

발생 시점. 입력 PDF가 지원 범위를 벗어날 때 객체 그래프 리더가 fail-closed로 이를 발생시킵니다. 리더는 고전적 교차 참조 테이블(ISO 32000-2:2020 §7.5.4), 교차 참조 스트림(§7.5.8), 객체 스트림으로 압축된 객체(§7.5.7), /Prev 체인을 통한 다중 개정(§7.5.6), /XRefStm을 통한 하이브리드 참조 파일(§7.5.8.4)을 지원합니다. 그 범위를 벗어난 것은 부분적이거나 추측된 파싱 대신 이 예외로 표면화됩니다. 이름 있는 생성자가 원인 사례로 매핑됩니다. encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile(), crossReferenceOffsetOutOfBounds()입니다.
담는 데이터. RuntimeException을 직접 확장하므로 컨텍스트 인식형이 아니며 getContext()가 없습니다. 호출자가 메시지를 파싱하지 않고 정확한 범주로 분기할 수 있도록 UnsupportedPdfStructureReason 타입(열거형)의 public readonly reason 속성을 노출합니다. 선택적인 detail 문자열과 previous throwable이 제한적이고 비민감한 컨텍스트를 더할 수 있습니다. 기본 메시지는 원인의 누설 없는 요약입니다.
복구. reason으로 분기하십시오. EncryptedDocument의 경우, 복호화는 리더의 범위 밖이므로 읽기 전에 복호화 단계를 실행하십시오. DamagedCrossReference, TruncatedFile, CrossReferenceOffsetOutOfBounds의 경우, 파일을 잘못된 형식이거나 불완전한 것으로 취급하고 소스를 다시 확보하거나 복구하십시오. CyclicReferenceChain, NonConformantObjectStream, IrresolvableObjectCollision의 경우, 입력이 구조 모델을 위반하므로 있는 그대로 읽을 수 없습니다.

`PacketTooLargeException`

발생 시점. 임베드된 XMP 패킷이 구성된 바이트 한도를 초과할 때 스트리밍 XMP 메타데이터 리더가 이를 발생시킵니다. 엔티티 확장 및 2차 폭증 유형의 입력에 대한 방어적 보호 장치입니다(기가바이트 규모의 임베드된 XMP에 대한 128 MB 피크 한도).
담는 데이터. NextPdfException을 확장하지만 getContext()를 재정의하지 않으므로 getContext()는 빈 배열을 반환합니다. 진단 데이터는 public readonly 속성에 있습니다. byteCount(관찰된 바이트 수)와 cap(바이트 단위로 구성된 한도)입니다. 메시지는 둘 다 보고합니다.
복구. 과도하게 큰 메타데이터를 악의적이거나 잘못된 형식으로 보고 거부하거나 건너뛰십시오. 정당한 문서가 실제로 더 큰 패킷을 필요로 한다면, 이 보호 장치가 방지하려는 메모리 소진 위험을 따져 가며 구성된 한도를 신중하게 높이십시오.

함께 보기

오류 참조 색인
폰트 및 태깅 문제 해결 — NotYetImplementedException, ScriptShaperException, IcuRequirementException 증상에 대해서입니다.
PDF/A 및 PDF/UA 검증 문제 해결 — Pdf14FeatureRejectedException과 Pdf20FeatureRejectedException 증상에 대해서입니다.
암호화 및 권한 문제 해결 — PublicKeyEncryptionUnsupportedException과 리더의 EncryptedDocument 원인에 대해서입니다.