# 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](https://zed.dev/docs/configuring-languages).

## 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.
