Felsökning
Diagnostisera vanliga fel
Varje meddelande nedan är den exakta text som Doconut producerar, organiserad efter symptom. Hitta ditt fel och tillämpa fixen.
Visaren visar ingenting
Tomt visningsområde, webbläsarkonsolen full av 404‑fel för /doconut-res/...
UseDoconutResources() saknas, eller placerad efter UseDoconut(). Den måste komma först i pipelinen.
Visaren rapporterar The viewer handler could not be reached (no response).
Begäran fick aldrig något svar. En vanlig orsak är en BasePath som börjar med /: '/doconut' blir //doconut/DocImage.axd, en begäran till en annan värd. Skriv den utan den inledande snedstrecket (BasePath: 'doconut').
Visaren rapporterar Please make sure your middleware is configured.
Sidans slutpunkt svarade 404: UseDoconut() är inte monterad där klientens BasePath pekar. Med app.Map("/doconut", branch => branch.UseDoconut()) använder klienten BasePath: 'doconut'.
HTTP 500 med:
Session middleware not configured. Call UseSession() before UseDoconut().Doconuts token‑säkerhet (aktiverad som standard) kräver ASP.NET‑sessionsstate. Lägg till builder.Services.AddSession() och app.UseSession() före Doconut‑middleware‑grenen. Sessionsstate behöver också en cache: i en minimal‑API‑app lägg till builder.Services.AddDistributedMemoryCache(), eller så stoppar appen vid start med Unable to resolve service for type 'IDistributedCache' (MVC‑ och Razor‑Pages‑appar registrerar redan en).
En felbild i sidområdet med texten:
You Are Not Authorized To View This Page.Tokenet öppnades av en annan webbläsarsession. Vanliga orsaker: sessions‑cookien når inte sidans begäranden (cross‑origin‑inställning, SameSite‑policy, en API‑klient utan cookie‑burk), eller så startade appen om (nya sessionsnycklar). Detta är säkerhetslagret som fungerar som designat — se Grundläggande koncept → Sessioner & Säkerhet. Avslaget är en bild som levereras med status 200, så en monitor som bara kontrollerar statuskoder räknar den som en sida.
En felbild med texten:
Document session not found. Please re-open document.Tokenet löpte ut (glidande fönster, standard 60 minuter — DocOptions.TimeOut) eller sessionen stängdes. Öppna dokumentet igen för ett nytt token.
Öppning av ett dokument misslyckas
LicenseException med ett avvisningsmeddelande — licensfilen hittades men avslogs (ogiltig signatur, manipulerad, svartlistad, eller en build utanför licensens versions-/uppdateringsfönster). Detta tillstånd blockerar öppning (fail‑fast) snarare än att degraderas till ett vattenmärke; läs License.RejectionMessage för orsaken.
LicenseException:
This document type requires the 'Dicom' plugin license.Filändelsen hanteras endast av ett plugin (här: DICOM). Pluginet är registrerat, men ingen licens ger dess funktionalitet längre — vanligtvis en temporär licens som löpte ut efter att appen startade. Installera en licens som beviljar den och verifiera IsCapabilityGranted(LicenseCapability.Dicom) på IDoconutLicenseService. En saknad eller otillräcklig icke‑temporär rättighet misslyckas normalt tidigare, under AddDoconut().
FormatNotSupportedException:
Document format '<extension>' is not supported.Ingen visare — inbyggd, plugin eller anpassad — påstår den filändelsen. Kontrollera listan över stödjade format; för egna format kan DoconutOptions.RegisterViewer lägga till ett.
InvalidDataException — filinnehållet är korrupt eller matchar inte filändelsen (t.ex. en omdöpt fil). Validera uppladdningar innan du öppnar.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().Du löste DocumentConverter utan att registrera Converter‑pluginet.
Startfel
InvalidOperationException nämner ett plugin registrerat via AddPlugin — den nuvarande icke‑temporära licensen ger inte den plugin‑kapaciteten. Ta bort registreringen eller installera en licens som ger den. En saknad licens och en äldre TRIAL‑fil ger inga plugin‑kapaciteter.
ArgumentException från AddDoconut():
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.Snabbfelvalidering — åtgärda den felaktiga sökvägen.
Bygg‑ / beroende‑fel
Kompileringsfel CS1705, eller vid körning när ett dokument öppnas:
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'Ditt projekt har låst System.Text.Json eller System.Text.Encodings.Web under 8.0.x‑beroendena som deklarerats av Doconut.NET8. Ta bort nedgraderingen och låt NuGet återställa paketgrafen (System.Text.Json 8.0.5 och System.Text.Encodings.Web 8.0.0).
Utdata ser felaktig ut
Sidor har ett vattenstämpel — appen är i ett utvärderingsläge: ingen licensfil hittades, en utgången temporär licens eller en ogiltig domän. Under en aktiv temporär licens är endast plugin‑utdata vattenmärkta. En byggnad som släpps efter ett betalt licensabonnemangs datum är inte vattenmärkt: öppning kastar LicenseException. Inspektera IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — Licenssidans IDoconutLicenseService‑referens visar en färdig endpoint.
Legacy‑dokument renderar förvrängd text — kodsidkodningar laddas inte som standard i .NET 8. Lägg till en gång vid start:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Felaktiga eller ersatta typsnitt — servern saknar dokumentets typsnitt. Installera dem, eller peka FontFolders (på WordConfig/PptConfig) mot en mapp som innehåller dem. På Linux, se nedan.
En bildanteckning visas i visaren men exporten har en "Image blocked"-ruta — bildens värd har en privat eller loopback‑adress, som servern vägrar att hämta. Se Anmärkningar.
Linux
Att öppna något dokument misslyckas med:
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.Installera fontkonfigurationsbiblioteket: apt-get install -y libfontconfig1 (fontconfig på RHEL/Fedora). Se Installation.
Att öppna något dokument misslyckas med:
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.Applikationen refererar till en nyare SkiaSharp, direkt eller via ett annat bibliotek. Lägg till SkiaSharp.NativeAssets.Linux i samma version som den SkiaSharp.
Att öppna något dokument misslyckas med:
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.Värden är inte en stödd plattform. Alpine och andra musl‑baserade distributioner stöds inte: använd en Debian‑ eller Ubuntu‑baserad avbild.
Texten är bredare eller smalare än på Windows, eller radbrytningar skiljer sig — dokumentets typsnitt är inte installerade, så Doconut använder det närmaste installerade typsnittet. Installera metrisk‑kompatibla typsnitt (fonts-liberation för Arial, Times New Roman och Courier New; fonts-crosextra-carlito och fonts-crosextra-caladea för Calibri och Cambria), eller kopiera dina egna licensierade typsnitt till /usr/share/fonts/ och kör fc-cache -f. Asiatisk text som visas som tomma rutor behöver fonts-noto-cjk.
Funktionen fungerade i utvärdering, tyst i produktion
Den klassiska go-live‑överraskningen: en aktiv Tillfällig licens ger varje funktion; din köpta licens ger bara det du köpte. Sök‑ och annoteringspaket kan försvinna när deras funktioner saknas. Registrerad Converter eller DICOM‑plugins med en otillräcklig icke‑tillfällig licens misslyckas under AddDoconut(). Jämför IsCapabilityGranted(...) med varje funktion du aktiverar innan driftsättning.
Sökning hittar ingenting (eller för lite)
- För en direkt PDF,
AllowSearchvar inte aktiverad vid öppning. Word, Excel och PowerPoint visar samma omkopplare via deras inbäddadePdfConfig. - Innehållet är skannat/endast bild, så vanlig Sökning har inget textlager att matcha mot. Använd en textbärande källa eller en PDF‑projektion som bevarar text.
- HTML och MS Project (MPP) är inte sökbara i sina standardinställningar — ställ in
DefaultRender = falseså att de renderas via en PDF‑projektion med ett inbyggt textlager. Word, Excel, PowerPoint, TXT, Visio, e‑post, EPUB och MHT söker i sina katalogstandarder. objViewer.CanSearch()ärfalseefter initiering — det lösta formatet har ingen standard sökväg. Detta beslut är separat från Sök‑licensen; verifiera båda.- Sidan läser returvärdet från
objViewer.Search(...)— räknaren kommer i dess tredje argument, en återuppringning.
Fortfarande fast?
Isolera problemet mot den minimala Quick Start‑appen; om det reproduceras där, kontakta support med dokumentet, din Program.cs och licensdiagnostikens utskrift.
Var den här sidan hjälpsam?