문제 해결

일반 오류 진단

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

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

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

뷰어가 The viewer handler could not be reached (no response).를 보고합니다
요청이 응답을 받지 못했습니다. 일반적인 원인은 BasePath가 /로 시작하는 경우입니다: '/doconut'가 //doconut/DocImage.axd가 되어 다른 호스트에 대한 요청이 됩니다. 선행 슬래시 없이 작성하세요 (BasePath: 'doconut').

뷰어가 Please make sure your middleware is configured.를 보고합니다
페이지 엔드포인트가 404로 응답했습니다: UseDoconut()가 클라이언트의 BasePath가 가리키는 위치에 마운트되지 않았습니다. app.Map("/doconut", branch => branch.UseDoconut())를 사용하면 클라이언트가 BasePath: 'doconut'를 사용합니다.

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 클라이언트) 또는 앱이 재시작됨(새 세션 키). 이는 설계된 대로 작동하는 보안 레이어이며 — Core Concepts → Sessions & Security를 참조하세요. 거부는 상태 200와 함께 제공되는 이미지이며, 상태 코드만 확인하는 모니터는 이를 페이지로 간주합니다.

오류 이미지 내용:

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

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

문서 열기 실패

LicenseException와 거부 메시지 — 라이선스 파일은 찾았지만 거부되었습니다(잘못된 서명, 변조, 블랙리스트에 등재, 또는 라이선스의 버전/업데이트 기간 외 빌드). 이 상태는 워터마크로 낮추는 대신 열기를 차단합니다(빠른 실패). 이유는 License.RejectionMessage를 참조하세요.

LicenseException:

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

해당 확장자는 플러그인(여기서는 DICOM)에서만 처리됩니다. 플러그인은 등록되어 있지만 더 이상 기능을 부여하는 라이선스가 없습니다 — 일반적으로 앱 시작 후 만료된 임시 라이선스입니다. 기능을 부여하는 라이선스를 설치하고 IDoconutLicenseService에서 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 에서 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 옵션 검증 — 문제 경로를 수정하십시오.

빌드 / 종속성 오류

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

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

프로젝트가 Doconut.NET8에서 선언한 8.0.x 종속성보다 낮은 버전의 System.Text.Json 또는 System.Text.Encodings.Web으로 고정되었습니다. 다운그레이드를 제거하고 NuGet이 패키지 그래프를 복원하도록 하세요 (System.Text.Json 8.0.5 및 System.Text.Encodings.Web 8.0.0).

출력이 잘못 표시됨

페이지에 워터마크가 표시됩니다 — 앱이 평가 모드에 있습니다: 라이선스 파일이 없거나, 만료된 임시 라이선스이거나, 도메인이 유효하지 않습니다. 활성 임시 라이선스에서는 플러그인 출력에만 워터마크가 적용됩니다. 유료 라이선스 구독 날짜 이후에 릴리스된 빌드는 워터마크가 없으며, 열 때 LicenseException 예외가 발생합니다. IDoconutLicenseService을 검사하십시오 (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — 라이선싱 페이지의 IDoconutLicenseService 참조가 준비된 엔드포인트를 보여줍니다.

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

잘못된 폰트 또는 대체 폰트 — 서버에 문서 폰트가 없습니다. 폰트를 설치하거나 FontFolders(WordConfig/PptConfig에) 폰트가 있는 폴더를 가리키게 하세요. Linux에서는 아래를 참고하십시오.

이미지 주석은 뷰어에 표시되지만 내보내기에서는 “Image blocked” 상자가 나타납니다 — 이미지 호스트가 사설 주소 또는 루프백 주소여서 서버가 가져오기를 거부합니다. 참조: 주석.

리눅스

문서를 열 때 다음 오류가 발생합니다:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

폰트 구성 라이브러리를 설치하십시오: apt-get install -y libfontconfig1 (RHEL/Fedora에서는 fontconfig). 참조: 설치.

문서를 열 때 다음 오류가 발생합니다:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

애플리케이션이 최신 SkiaSharp을 직접 또는 다른 라이브러리를 통해 참조하고 있습니다. 해당 SkiaSharp과 동일한 버전의 SkiaSharp.NativeAssets.Linux을 추가하십시오.

문서를 열 때 다음 오류가 발생합니다:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

호스트가 지원되는 플랫폼이 아닙니다. Alpine 및 기타 musl 기반 배포판은 지원되지 않으며, Debian 또는 Ubuntu 기반 이미지를 사용하십시오.

텍스트가 Windows보다 넓거나 좁게 표시되거나 줄 바꿈이 다르게 나타납니다 — 문서의 폰트가 설치되지 않아 Doconut이 가장 가까운 설치된 폰트를 사용합니다. 메트릭 호환 폰트를 설치하십시오 (fonts-liberation는 Arial, Times New Roman 및 Courier New용; fonts-crosextra-carlito와 fonts-crosextra-caladea는 Calibri 및 Cambria용), 또는 라이선스가 있는 자체 폰트를 /usr/share/fonts/에 복사하고 fc-cache -f을 실행하십시오. 아시아 텍스트가 빈 상자로 표시되는 경우 fonts-noto-cjk가 필요합니다.

평가에서는 기능이 작동하고, 프로덕션에서는 조용함

클래식한 실시간 가동 서프라이즈: 활성 임시 라이선스는 모든 기능을 부여하지만, 구매한 라이선스는 구매한 것만 부여합니다. 검색 및 주석 번들은 해당 기능이 없을 때 사라질 수 있습니다. 등록된 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 라이선스와 별개이며, 둘 다 확인하십시오.
  • 페이지는 objViewer.Search(...) 의 반환 값을 읽습니다 — 카운트는 세 번째 인자인 콜백으로 전달됩니다.

아직도 막혔나요?

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

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