문제 해결

일반 오류 진단

아래의 모든 메시지는 Doconut이 실제로 출력하는 텍스트이며, 증상별로 정리되었습니다. 오류를 찾아 해결책을 적용하세요.

뷰어에 아무 것도 표시되지 않음

뷰어 영역이 비어 있고, 브라우저 콘솔에 /doconut-res/...에 대한 404가 가득함
UseDoconutResources()가 없거나 UseDoconut() 뒤에 배치되었습니다. 파이프라인에서 가장 먼저 호출되어야 합니다.

HTTP 500 및 다음 메시지:

text
Session middleware not configured. Call UseSession() before UseDoconut().

Doconut의 토큰 보안(기본 활성화)에는 ASP.NET 세션 상태가 필요합니다. builder.Services.AddSession()와 app.UseSession()을 Doconut 미들웨어 분기 앞에 추가하세요. 세션 상태에는 캐시도 필요합니다: 최소 API 앱에서는 builder.Services.AddDistributedMemoryCache()를 추가하고, 그렇지 않으면 Unable to resolve service for type 'IDistributedCache' 오류와 함께 앱이 시작 단계에서 중단됩니다(MVC 및 Razor Pages 앱은 이미 등록되어 있음).

페이지 영역에 다음과 같은 오류 이미지가 표시됨:

text
You Are Not Authorized To View This Page.

토큰이 다른 브라우저 세션에서 열렸습니다. 일반적인 원인: 세션 쿠키가 페이지 요청에 도달하지 않음(교차 출처 설정, SameSite 정책, 쿠키 저장소가 없는 API 클라이언트), 혹은 앱이 재시작되어 새로운 세션 키가 생성된 경우입니다. 이는 설계된 보안 레이어가 작동하고 있는 것이며, Core Concepts → Sessions & Security 를 참고하세요.

다음과 같은 오류 이미지가 표시됨:

text
Document session not found. Please re-open document.

토큰이 만료되었거나(슬라이딩 윈도우, 기본 60분 — DocOptions.TimeOut) 세션이 종료되었습니다. 새 토큰을 얻기 위해 문서를 다시 열어 주세요.

서버는 정상인데 페이지가 오류 없이 이상 동작함

다음은 애플리케이션을 이전한 뒤 처음 의심해볼 실패 모드입니다. 세 경우 모두 서버는 정상적으로 작동하고, 문서는 올바르게 렌더링되며, 브라우저 콘솔에도 아무 메시지가 나타나지 않습니다.

끝없이 돌아가는 로딩 스피너
뷰어 콜백이 전역 함수로 선언되어야 하는데, 컨테이너 ID 뒤에 이름이 붙은 ctlDoc_OnViewerReady() 등으로 선언되지 않았습니다. 이전 뷰어는 해당 이름을 찾아 사용했지만, 현재 뷰어는 찾지 못해 스피너를 숨기는 핸들러가 실행되지 않습니다. 옵션으로 함수를 전달하세요:

javascript
objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

스피너 뒤의 문서는 정상입니다. 전체 옵션 목록은 뷰어 구성 에 있습니다.

뷰어 아이콘이나 크롬이 누락되고, 페이지는 정상
ResPath가 비어 있거나 애플리케이션 루트를 가리키고 있습니다 — 이전 라이브러리에서는 맞았지만 여기서는 틀렸습니다. UseDoconutResources()가 마운트하는 접두사를 지정해야 합니다:

javascript
ResPath: 'doconut-res/images'   // 또는 '<your ResourcesPath>/images'

공유 스토리지에서 제공할 때 뒤쪽 페이지의 타일이 깨짐
아직 쓰여지고 있는 페이지는 202 Accepted 응답을 반환합니다. retryOn409: true 옵션이 없는 클라이언트는 이를 실패한 이미지로 처리합니다. 분산 배포 를 참고하세요.

문서 열기 실패

LicenseException과 거부 메시지 — 라이선스 파일은 발견됐지만 거부되었습니다(서명 불일치, 변조, 블랙리스트, 혹은 라이선스 버전/업데이트 창을 벗어난 빌드). 이 상태에서는 문서 열기가 차단됩니다(빠르게 실패). 이유는 License.RejectionMessage에서 확인할 수 있습니다.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

해당 확장자는 플러그인(예: DICOM)으로만 처리되며, 현재 권한이 부여되지 않았습니다. 플러그인을 등록하고 lic.IsCapabilityGranted(LicenseCapability.Dicom)을 확인하세요. 비임시 권한이 없으면 AddDoconut() 단계에서 이미 실패합니다.

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

내장, 플러그인, 혹은 사용자 정의 뷰어 중 어느 것도 해당 확장자를 지원하지 않습니다. 지원되는 형식 목록을 확인하고, 자체 형식의 경우 DoconutOptions.RegisterViewer를 사용해 추가하세요.

InvalidDataException — 파일 내용이 손상됐거나 확장자와 일치하지 않습니다(예: 파일명을 변경한 경우). 열기 전에 업로드 파일을 검증하세요.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentConverter를 사용했지만 변환기 플러그인을 등록하지 않았습니다. 플러그인을 추가하세요.

시작 시 실패

InvalidOperationException mentioning a plugin registered via AddPlugin — 현재 비임시 라이선스는 해당 플러그인 기능을 부여하지 않습니다. 등록을 제거하거나 해당 기능을 부여하는 라이선스를 설치하십시오. 라이선스가 없고 레거시 TRIAL 파일이 있으면 플러그인 기능이 전혀 부여되지 않습니다.

ArgumentException from AddDoconut():

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

옵션 검증이 즉시 실패합니다 — 문제의 경로를 수정하십시오.

빌드 / 종속성 오류

The package will not install at all — Doconut.NETStandard 26.8.0은 netstandard2.1을 대상으로 하므로 NuGet이 .NET Framework 프로젝트를 거부합니다. 이는 복구 가능한 오류가 아닙니다: .NET Framework는 netstandard2.1을 사용할 수 없습니다. 대신 Doconut.NETFramework 패키지를 사용하십시오.

Compiler error CS1705, or at runtime when opening a document:

text
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

프로젝트가 System.Text.Json 또는 System.Text.Encodings.Web을 9.0.x 이하 버전으로 고정했기 때문에 발생합니다. 다운그레이드를 제거하고 NuGet이 패키지 그래프(System.Text.Json 9.0.0 및 System.Text.Encodings.Web 9.0.0)를 복원하도록 하십시오 (감사된 26.8.0 패키지에 포함).

A wall of compile errors immediately after bumping the package — 이는 예상된 동작입니다. 26.8.0은 26.7.0과 다른 API 표면을 가지고 있어 호환 업데이트가 아닙니다. 대부분의 오류는 using 라인이 루트 Doconut 네임스페이스로 이동했기 때문이며, 하나씩 패치하기보다 .NET Standard 2.1로 마이그레이션을 진행하십시오.

TypeInitializationException on the first presentation file:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

프레젠테이션 엔진은 패키지에 선언된 System.Drawing.Common 6.0.0을 강제로 요구합니다. 해당 종속성을 제거하거나 재정의하지 마십시오 — 이 라이브러리가 없으면 모든 PPT/PPTX/PPS/POT/ODP 파일을 열 수 없습니다.

출력이 잘못 보임

Pages carry a watermark — 앱이 평가 모드에 있습니다: 라이선스 파일이 없거나, 만료된 임시/구독 창이 있거나, 도메인이 유효하지 않습니다. IDoconutLicenseService(License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage)를 확인하십시오 — 라이선싱 페이지의 IDoconutLicenseService 참조가 준비된 엔드포인트를 보여줍니다.

Legacy documents render garbled text — 코드 페이지 인코딩이 기본적으로 로드되지 않습니다. 시작 시 한 번 추가하십시오:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Wrong or substituted fonts on Linux/Docker — 컨테이너에 문서에 필요한 폰트가 없습니다. FontFolders(WordConfig/PptConfig에 있음)를 마운트된 폰트 디렉터리로 지정하십시오.

Presentations open but fail to render on Linux/macOS — 현재 PPT/PPTX/PPS/POT/ODP 렌더러는 네이티브 libgdiplus와 System.Drawing.EnableUnixSupport=true가 필요합니다. 패키지는 이 스위치를 지원하는 마지막 버전인 System.Drawing.Common 6.0.0을 제공합니다.

평가에서는 작동했지만, 프로덕션에서는 작동 안 함

클래식한 실시간 배포 서프라이즈: 활성 임시 라이선스는 모든 기능을 부여하지만, 구매한 라이선스는 구매한 기능만 부여합니다. 검색 및 주석 번들은 해당 기능이 없을 경우 사라질 수 있습니다. 충분하지 않은 비임시 라이선스로 등록된 Converter 또는 DICOM 플러그인은 AddDoconut() 중에 실패합니다. 배포 전에 활성화하려는 모든 기능에 대해 IsCapabilityGranted(...)를 비교하십시오.

검색 결과가 없음 (또는 너무 적음)

  • 직접 PDF인 경우, 열 때 AllowSearch가 활성화되지 않았습니다. Word, Excel, PowerPoint도 동일한 스위치를 중첩된 PdfConfig를 통해 제공합니다.
  • 내용이 스캔된 이미지 전용이라면 일반 검색에 매치할 텍스트 레이어가 없습니다. 텍스트가 포함된 소스나 텍스트를 보존하는 PDF 투영을 사용하십시오.
  • HTML 및 MS Project(MPP)는 기본 설정으로 검색할 수 없습니다 — DefaultRender = false로 설정하면 네이티브 텍스트 레이어가 있는 PDF 투영으로 렌더링됩니다. Word, Excel, PowerPoint, TXT, Visio, 이메일, EPUB, MHT는 카탈로그 기본값에서 검색됩니다.
  • 초기화 후 objViewer.CanSearch()가 false이면, 해석된 형식에 표준 검색 경로가 없습니다. 이는 Search 라이선스와 별개의 판단이므로 두 가지를 모두 확인하십시오.

아직도 문제가 있나요?

문제를 최소 Quick Start 앱에 격리해 보세요; 해당 앱에서 재현된다면, 문서와 Program.cs, 그리고 라이선스 진단 출력을 함께 지원팀에 문의하십시오.

이 페이지가 도움이 되었나요?