On this page
Diagnose an integration failure
Resolve restore, SDK, documentation, security and scheduling failures.
Follow the failing boundary before changing dependencies or disabling checks.
Restore cannot authenticate
A successful git credential does not prove NuGet package-read access. Verify the feed name, source mapping and runtime credential scope. Never paste a token into an issue or build log. A 401/403 is not fixed by changing package versions.
The SDK is missing
Source verification requires the SDK in global.json. Install/select that SDK and set DOTNET_HOST_PATH when the verification runner should launch a specific dotnet executable. Do not silently downgrade global.json to match a workstation.
Run dotnet --version from the checkout as well as the editor's terminal. The CLI host selected by PATH determines which SDK installations it can discover; a newer SDK installed elsewhere does not repair a different host automatically. Use a persistent installation directory, not a temporary test SDK. For a user-level macOS/Linux installation, set DOTNET_ROOT to $HOME/.dotnet and prepend that directory to PATH in the login shell.
For Zed/Roslyn, merge the matching DOTNET_ROOT, DOTNET_HOST_PATH and PATH into lsp.roslyn.binary.env in personal settings, then restart the language server. Keep machine-specific absolute paths outside repository settings. Confirm the Roslyn logs show the expected build host and successful solution loading. See Zed language-server configuration.
Imports look unused in the editor
Check the actual IDE0005 diagnostic rather than inferring it from syntax colors. Run the repository verification gate; it checks unused imports with documentation parsing enabled and includes a negative package-consumer fixture. If an editor disagrees, inspect project-load diagnostics, SDK selection and generated global imports before removing directives. An import is required when removing it from the same compilation leaves referenced types or extension methods unresolved.
Documentation export rejects the version
Build the selected configuration after changing the source version. The manifest version must match every compiled package's informational version. Do not publish a development API catalog under a stable release route.
Documentation export rejects a link
Use doc:stable-page-id or doc:stable-page-id#heading-anchor. The target page and anchor must exist. External links use absolute HTTPS URLs. Export refuses invalid paths, symlink inputs and undeclared package references rather than scanning the filesystem for something that looks plausible.
OpenAPI or timing is absent in production
This is the default when no production disclosure/authorization policy is supplied. Configure the actual policy and authenticate the caller; do not bypass it for a documentation widget. The same protection must cover the OpenAPI document itself.
A scheduled task ran twice
Cron calculation is not a durable scheduler. Verify product-owned occurrence IDs, leases, transaction boundaries and idempotency. SMTP acceptance cannot be rolled back with the database; preserve uncertain outcomes for recovery.
Upgrading a consumer
Pin a published version, regenerate lock files deliberately, then restore in locked mode and run the consumer's build, database tests and runtime smoke checks. Packages version together while MAJOR is zero, but introducing an adapter still requires host configuration. Preserve applied migration history and keep product-owned tables.