Isolated .NET SDK Exact SDKs without changing system .NET

Troubleshooting and safe recovery

The tool deliberately fails rather than guessing when SDK metadata, integrity checks, isolated-host proof, or destructive-operation safety cannot be established. Do not disable checksums, remove unrelated SDKs, or delete a conflicting directory just to make an error disappear.

Use the Windows / PowerShell 7 or Linux and macOS / Bash guide for exact command syntax. Start by noting the operation, requested exact SDK version, diagnostic text, and exit status. You can retry transient network failures, but repeated failures deserve investigation; record the diagnostics before cleaning up your own files.

Find the safe next step

Symptom or situation What it means Safe response
Stable bootstrap cannot resolve a release, download the product script/checksum, or match SHA256SUMS. The latest-stable or pinned bootstrap has not established a verified released product script. The short Pages entry point itself is trusted through HTTPS; it cannot authenticate its own piped bytes. Confirm network availability and the trusted project URLs; retry the documented bootstrap when delivery is healthy. Do not execute the unverified downloaded script or substitute a mutable development source to work around checksum failure. The existing saved tool is recovery state if replacement could not complete.
Install picker cannot load Microsoft channels/versions, or an exact-version Install cannot resolve/download its Microsoft artifact metadata. Required Microsoft release information or a matching archive is unavailable/unusable. An exact version skips the channel picker, not the artifact metadata/checksum requirement. Check the exact version, platform, Microsoft metadata service, and connectivity; retry later if the failure is transient. Do not install an archive outside the verified path merely to bypass the error.
Install checksum fails or metadata has no usable digest. The downloaded payload was not proven to match Microsoft’s published artifact checksum; extraction/promotion must not proceed. Modern SDKs require SHA-512; eligible historical .NET 1.x payloads can use Microsoft-published SHA-256. Do not extract or execute the failed payload. Verify the upstream artifact metadata and retry through the normal tool after the cause is resolved; never disable the checksum requirement.
An isolated version destination already exists but is invalid or a promotion conflicts. The selected version path may contain user/recovery data or an installation that does not pass exact isolated-version/origin proof. The tool deliberately does not overwrite, adopt, or delete it. Inspect and preserve the existing path before making an explicit manual decision about it. Resolve the conflict only when you have positively identified its contents and know they are backed up or expendable. Retry Install afterward. Do not blindly recursively delete the SDK root.
Staged SDK host verification fails during Install. The extracted host did not prove the requested exact version and isolated origin, or could not run on the current platform. Older SDKs may have host/runtime prerequisites that are unavailable on modern systems. Read the error and compare the exact version/platform against published SDK compatibility. Install does not promote an unverified new SDK. It attempts cleanup of operation-owned staging/metadata/archive files; do not assume failed staging remains for debugging. A cleanup failure is itself reported.
Verify reports Microsoft release/lifecycle information unavailable, but local checks say OK and the command exits successfully. Release metadata enrichment is optional; local version/origin checks remain the success authority. Verify may attempt a network request without making the network a prerequisite for successful local verification. Treat the local SDK as verified within Verify’s documented scope. Retry later only if you need lifecycle/servicing information. Use Audit when you specifically need up-to-date online metadata.
Verify reports a local FAIL (host, inventory/origin, or exact SDK resolution). The exact isolated SDK has not passed local proof, regardless of optional metadata. Modern hosts use isolated --list-sdks and --version; original 1.x/early 2.x use pinned --version plus --info SDK Base Path. Read the failed check and inspect the expected isolated version directory. Ensure the host is runnable and the version really comes from that root. Do not treat an equal-version System SDK as proof, and do not assume Verify repairs installations.
Audit fails while loading Microsoft metadata. Audit is an explicit online report and cannot reliably classify all recognized installed SDKs without required metadata; it exits nonzero instead of fabricating or silently omitting lifecycle results. Retry when Microsoft metadata is available. Use List for immediate local inventory; unlike Audit, List does not require online metadata.
Remove is cancelled or no input/approval is available. Remove is default-no. Automatic confirmation is never inferred from an unavailable prompt. Supply a supported explicit approval only after confirming the exact isolated SDK being removed: PowerShell -Yes / Bash --yes; PowerShell also supports -WhatIf for preview and native -Confirm. Never point Remove at a System SDK.
Remove reports build-server shutdown or temporary-state cleanup failure. A supported shutdown operation actually attempted, or required preflight, has failed; deletion must not proceed. Address the underlying process/permissions error before retrying. Eligible historical stable SDKs with both public shutdown spellings positively classified as unavailable are handled automatically after ordinary confirmation; no extra flag is required. Early 2.1.1xx/2.1.2xx SDKs additionally require targeted Roslyn shutdown to succeed. A hostless or unusable-host SDK folder can instead be selected as (incomplete) and removed with an informative no-shutdown warning.
Remove cannot rename the SDK directory, but reports that the original installation remains intact. Windows may deny a directory rename because a process holds a file open, because of permissions, or because of another filesystem restriction. The application verified that staging did not move the SDK and cleaned its temporary recovery files. An “access denied” error alone does not identify the cause. Inspect the reported process and ACL hints, release any open handles or resolve permissions, and retry ordinary Remove. On Windows, use Resource Monitor’s CPU > Associated Handles search to investigate suspected file locks and icacls "<SDK directory>" to inspect permissions. The tool does not automatically terminate arbitrary processes or change access controls.
Remove reports incomplete removal after staging. The approved SDK was moved into operation-owned quarantine but not all files could be deleted; its executable may already be absent. Close blocking processes or fix permissions, then run Remove again and select the clearly labeled incomplete removal (or supply the same exact version). Confirm normally. Do not alter hidden recovery records or manually adopt arbitrary folders. A missing/mismatched recovery proof requires manual investigation, not a forced deletion.
Operation-owned cleanup fails after an installation attempt. Cleanup failures are surfaced; an already promoted SDK may be usable even if cleanup caused the overall operation to report failure. Do not infer state solely from the exit message. Inspect the final selected version and, if present, use Verify’s local proof before deciding what to keep. Distinguish the final SDK from temporary operation-owned files and preserve unrelated content.

On Windows, PowerShell removal failures display a colored Error heading and a Diagnostics section with nested troubleshooting guidance. The original underlying exception appears in the PowerShell error record, not in a duplicated Details section. Diagnostics inspect running processes whose executable or command line references the SDK and attempt a read-only ACL check. A matching process is not proof that it owns a blocking file handle; no matching process does not exclude locks held by an editor, shell, antivirus, or another application. Reading an ACL does not prove that the current user has effective rename/delete permissions. This inspection is best-effort and does not modify files or permissions. For ambiguous failures, investigate handles and effective permissions before retrying.

Find a Windows file-lock holder

  1. Run resmon.exe, open CPU > Associated Handles, and use the Search Handles field.
  2. Enter part of the full file path, not necessarily a process name. For example, try the SDK version folder (99.0.189), its parent directory (dotnet-sdks for the default installation), or a suspected locked filename (issue-186-lock-test.tmp). If one search yields no results, try a different part of the path.
  3. Inspect the result’s Image (process name) and PID to identify the process holding the handle. A PowerShell window (pwsh.exe) or editor may hold a file even when its executable and command line do not mention that SDK. A matching handle is a clue, not definitive proof of which handle prevented the directory rename; no match does not rule out a lock.

After identifying a likely owner, close or stop that application normally, then retry Remove. Do not forcibly close another process’s handles or terminate an unrelated process. Resource Monitor is built into Windows; no additional utility is required.

Choose the right diagnostic command

  • List answers which SDKs are installed, and where? It is local and network-independent, and reports Isolated and read-only System SDKs separately.
  • Verify answers does this exact isolated SDK resolve correctly? Local checks determine success/failure; optional online metadata and component diagnostics can be unavailable.
  • Audit answers what are the current lifecycle and servicing states of installed SDKs? It requires usable online Microsoft metadata when recognized SDKs are installed.

A successful Verify does not compile your project, scan for vulnerabilities, or authenticate Microsoft independently. It does not rehash the originally downloaded archive; that integrity check was performed during Install. For an actual build, use the version-specific isolated host, and choose a project global.json policy deliberately.

Deeper guarantees and recovery boundaries