문제 해결

일반 오류 진단

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

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

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

HTTP 500 발생:

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

Doconut의 토큰 보안(기본 활성화)은 ASP.NET 세션 상태가 필요합니다. Doconut 미들웨어 분기 앞에 builder.Services.AddSession() 와 app.UseSession() 를 추가하세요. 세션 상태에는 캐시도 필요합니다: 최소 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 클라이언트), 또는 앱이 재시작되어 새로운 세션 키가 생성된 경우. 이는 설계된 보안 레이어가 작동하고 있는 것이며 — 핵심 개념 → 세션 및 보안을 참고하세요.

오류 이미지가 표시됨:

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 를 해결했지만 Converter 플러그인을 등록하지 않았습니다.

시작 실패

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.

Fail-fast 옵션 검증 — 문제 경로를 수정하십시오.

빌드 / 종속성 오류

패키지를 전혀 설치할 수 없습니다 — Doconut.NETStandard 26.8.0은 netstandard2.1을 대상으로 하므로 NuGet이 .NET Framework 프로젝트를 거부합니다. 이는 해결 가능한 복원 오류가 아닙니다: .NET Framework은 netstandard2.1을 사용할 수 없습니다. 대신 Doconut.NETFramework 패키지를 사용하십시오.

컴파일러 오류 CS1705, 또는 문서를 열 때 런타임 오류:

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

프로젝트가 System.Text.Json 또는 System.Text.Encodings.Web를 Doconut.NETStandard이 선언한 9.0.x 종속성보다 낮게 고정했습니다. 다운그레이드를 제거하고 NuGet이 패키지 그래프를 복원하도록 하세요 (감사된 26.8.0 패키지에서 System.Text.Json 9.0.0 및 System.Text.Encodings.Web 9.0.0).

패키지를 업데이트한 직후에 발생하는 다수의 컴파일 오류 — 이는 예상된 동작입니다. 26.8.0은 26.7.0과 다른 API 표면이며 호환되는 업데이트가 아닙니다. 대부분의 오류는 루트 Doconut 네임스페이스로 이동한 using 라인입니다; 하나씩 패치하기보다 Migrate to .NET Standard 2.1 를 진행하십시오.

TypeInitializationException 첫 프레젠테이션 파일에서:

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

프레젠테이션 엔진은 System.Drawing.Common 6.0.0 (패키지에 선언됨)을 강제 요구합니다. 해당 종속성을 제거하거나 재정의하지 마십시오 — PPT/PPTX/PPS/POT/ODP를 열 때마다 이가 없으면 실패합니다.

출력이 잘못 표시됨

페이지에 워터마크가 표시됩니다 — 앱이 평가 모드에 있습니다: 라이선스 파일이 없거나, 임시 또는 구독 라이선스가 만료되었거나, 도메인이 유효하지 않습니다. IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage)을 확인하십시오 — 라이선스 페이지의 IDoconutLicenseService 참조가 준비된 엔드포인트를 보여줍니다.

레거시 문서가 깨진 텍스트로 렌더링됩니다 — 코드 페이지 인코딩이 기본적으로 로드되지 않습니다. 시작 시 한 번 추가하십시오:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Linux/Docker에서 잘못된 폰트 또는 대체 폰트 — 컨테이너에 문서 폰트가 없습니다. FontFolders (WordConfig/PptConfig에) 를 마운트된 폰트 디렉터리로 지정하십시오.

프레젠테이션은 열리지만 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입니다 — 해결된 형식에는 표준 검색 경로가 없습니다. 이 판단은 검색 라이선스와 별개이며, 두 가지를 모두 확인하십시오.

아직도 막히셨나요?

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

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