Troubleshooting

SharpDocs validates aggressively at startup, so most problems surface as a clear exception in the host log or a degraded card on the landing page. This page maps the symptoms to the fix.

Site fails to boot

These three are always fatal — the host won't serve any traffic until you fix them.

DirectoryNotFoundException: Docs root not found: ...

SharpDocs:DocsRoot resolved to a folder that doesn't exist. Relative paths resolve against IHostEnvironment.ContentRootPath. Check the path from where the app is launched, not where the project lives.

FileNotFoundException: SharpDocs requires a sharpdocs.json at the docs root

The folder exists but has no sharpdocs.json. Create one — even an empty single-project shape works:

{ "title": "My site", "sidebar": [] }

sharpdocs.json references slug 'foo/bar' but no matching markdown page was found.

Sidebar references a slug that doesn't resolve. Single-project: this is fatal. Multi-project: this only degrades the offending project; the rest of the site still boots. Either remove the sidebar entry or create the file.

Slug rules: file path under the project's docs root, extension stripped, \ → /, trailing /index collapsed.

A project shows a warning panel on the landing page

Multi-project only. The project failed to load and was degraded — the rest of the site is fine. Common causes:

Error message starts with…	What it means
Project directory not found:	The path in the root projects[] doesn't resolve to a folder.
Per-project sharpdocs.json not found:	Folder exists but has no sharpdocs.json next to its markdown.
sharpdocs.json references slug ...	Sidebar typo in the project's config.
Project id '...' is reserved.	Pick a different id. Reserved: search, packages, v3, api, docs.

Fix the underlying issue, restart the host, refresh the landing page.

Feed is empty / a package isn't appearing

LocalFolderSource only sees what was on disk at startup. There's no file watcher.

1. Confirm the file is in the right folder. Single-project: SharpDocs:ArtifactsRoot (default artifacts). Multi-project: the project's artifacts (default ./artifacts relative to the project).
2. Confirm it ends in .nupkg, not .snupkg or *.symbols.nupkg (those are filtered out).
3. Restart the host. The feed re-scans on boot.
4. Hit /packages/{id} — if it 404s, the file isn't being read; if it loads with no versions, the nuspec parsing failed (check the host log).

NuGet feed URLs are wrong behind a proxy

The feed builds absolute URLs from the incoming request's Scheme/Host/PathBase. If those reflect an internal address, dotnet restore will hit URLs that don't resolve publicly. See Host behind a reverse proxy for forwarded-headers setup.

Search returns nothing

• The endpoint is per-project. Single-project: /search?q=.... Multi-project: /docs/{projectId}/search?q=.... There is no unified /search in multi-project mode — it 404s.
• The scorer is literal: no stemming, no fuzzy match. auth will not match authentication.
• Search only indexes pages reachable on disk. New pages appear after a host restart.

Multi-project landing page rendered the picker, but I only have one project

The single-healthy-project shortcut requires the project's sidebar to define an index slug (so HomeController has something to render). If your one project has no index, the picker is shown instead. Add an index.md and a sidebar entry for it.

Package versions out of order

Versions are sorted ascending; the last one is "latest" for search and registration. If you see an older version listed as latest, check the file actually exists in the artifacts folder and that the nuspec inside it has the version you expect.

Where to look next

• Host log — every degraded project, slow upstream, or unreadable nupkg is logged with context.
• /api/manifest — JSON snapshot of what the registry actually loaded, including each project's error field. Hit it to confirm the runtime state matches your intent.