문제 해결

일반 오류 진단

아래의 모든 메시지는 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 가 거부 메시지와 함께 — 라이선스 파일은 발견되었지만 거부되었습니다(잘못된 서명, 변조, 블랙리스트에 포함, 또는 라이선스 버전/업데이트 기간 외의 빌드). 이 상태는 워터마크로 낮추는 대신 열기를 차단합니다(fail-fast); 이유는 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 가 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 옵션 검증 — 문제 경로를 수정하십시오.

빌드 / 종속성 오류

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

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

프로젝트가 System.Text.Json 또는 System.Text.Encodings.Web 를 Doconut.NET6 가 선언한 8.0.x 종속성 이하로 고정했습니다. 다운그레이드를 제거하고 NuGet이 패키지 그래프를 복원하도록 하십시오 (System.Text.Json 8.0.6 및 System.Text.Encodings.Web 8.0.0은 패키지에 선언된 대로).

출력이 잘못 표시됨

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

잘못된 또는 대체된 폰트 — 서버에 문서 폰트가 없습니다. 폰트를 설치하거나 FontFolders (WordConfig/PptConfig 에서) 를 폰트가 들어 있는 폴더로 지정하십시오. Linux에서는 아래를 참조하십시오.

뷰어에 이미지 주석이 표시되지만 내보내기에는 "이미지 차단됨" 상자가 있습니다 — 이미지 호스트가 사설 또는 루프백 주소여서 서버가 가져오기를 거부합니다. 참조: 주석.

리눅스

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

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, 그리고 라이선스 진단 출력을 함께 지원팀에 문의하십시오.

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