# Diagnose extension installation failures in 3D Slicer

Diagnose 3D Slicer extension installation failures: classify 'Failed downloading' network errors, loadSourceAsModule revision mismatches, missing-modules-after-install (restart), Extensions Manager crashes on Linux (QtWebEngine/OpenGL), and catalog coverage gaps; includes the offline install-from-file procedure.

Exact reference: {"kind":"skill_version","skill_id":"skl_vBMcMdywlkFcmM684dL2Vw","version_id":"skv_3B63MbnvCFrHi6xKD0zSDw"}

Applicability: [{"constraint":">=5.0","technology":"3D Slicer","version_scheme":"semver"}]

# Diagnose extension installation failures in 3D Slicer

Use this when an extension won't download, installs but its modules never
appear, or the Extensions Manager itself misbehaves. Extensions are built for a
specific Slicer **revision** (e.g. `Extensions-31938` under Slicer 5.4.0,
`Extensions-32448` under Slicer 5.6.2) — most failures are a mismatch between
the extension package and your Slicer build, or a network problem. Find your
revision in **Help / About**; the catalog uses it in the URL
(`extensions.slicer.org/catalog/All/32448/win`).

## 1. `Failed downloading: https://slicer-packages.kitware.com/...`

The Extensions Manager could not fetch the package — this is a network problem,
not a broken extension. It shows up on locked-down machines, proxies, and
cloud VMs (firewalled govcloud instances hit it for every extension). Fix:

1. Download the extension package from the catalog website on a machine that
   has network access. Pick the entry matching **your OS and your Slicer
   revision**.
2. In Slicer's Extensions Manager, use **Install extension from file**
   (wrench/toolbox menu) and select the downloaded package.
3. Restart Slicer.

The same offline path works on air-gapped machines; the documented section is
"Install extensions without network connection" in the user guide.

## 2. Installed, but the module never appears / `loadSourceAsModule - Failed to load`

Real symptom, from the Error Log:

```
loadSourceAsModule - Failed to load file "C:/.../Extensions-32448/OpenDose3D/lib/Slicer-5.6/qt-scripted-modules/OpenDose3D.py" as module "OpenDose3D" !
Fail to instantiate module "OpenDose3D"
The following modules failed to be instantiated: Calibration OpenDose3D Gamma
```

This means the extension package was built against a **different Slicer
version** than the one running — e.g. OpenDose3D packages that predate a Slicer
5.8 update and no longer load under it. Check, in order:

1. Does your Slicer's revision match the revision the package was built for?
   Extension folders are named `Extensions-[revision]`; a folder whose revision
   differs from Help / About is the wrong package.
2. If the versions genuinely differ, either install the Slicer version the
   extension targets, or check the extension's own issue tracker — extension
   authors announce compatibility updates there.

Note the distinction from the next case: here the load is *attempted* and
fails. If no load is attempted at all, see below.

## 3. Extension shows "installed" but nothing new in the module list

Extensions are not activated until Slicer **restarts**. This is the most common
"it installed but I can't find it" report: the install completed, the module
only registers on the next launch. Restart Slicer, then check the Extensions
Manager's Installed tab. (If you installed from a file per section 1 and the
module still doesn't appear after a restart, you are in section 2 territory —
verify the package revision.)

## 4. Extensions Manager crashes or shows a blank/no-connection page

On Linux, opening the Extensions Manager has crashed Slicer outright
(QtWebEngine + OpenGL stack traces ending in `QQuickWidget`/`RenderWidgetHostViewQtDelegateWidget`
segfaults, after `[Qt] An OpenGL Core Profile was requested, but it is not
supported` warnings). This is a rendering-environment problem, not a catalog
problem:

- Update the graphics driver / enable a supported OpenGL profile if you can.
- Otherwise skip the in-app browser entirely: use the offline install-from-file
  flow from section 1.

## 5. Extension missing from the catalog for your revision

Some extensions are only built for certain platforms or for preview (nightly)
builds. Search the catalog for your exact revision and OS; if the extension is
absent there but exists for the nightly, install a Slicer preview release and
retry. If it is absent for your OS entirely, the extension does not support
that platform (check its repository for a platform-support statement before
assuming the catalog is broken).

## Quick triage checklist

1. Capture the exact symptom: download error, load error in the Error Log,
   missing-after-restart, or manager crash.
2. Network → offline install from file (section 1).
3. `loadSourceAsModule` failure → revision mismatch (section 2).
4. Installed-but-missing → restart Slicer (section 3).
5. Manager crash → graphics environment; use offline install (section 4).
6. Not in catalog → platform/nightly coverage (section 5).


## Supporting basis and limitations

Built from 3D Slicer Discourse threads: 'Extension download issues in govcloud' (Failed downloading + offline install-from-file procedure), 'OpenDose3D module is not loaded' (loadSourceAsModule / failed-to-instantiate on a version mismatch, Extensions-32448 under Slicer 5.6.2), 'Opening extension manager makes Slicer crash on Linux' (QtWebEngine OpenGL crash), and the Extensions Manager user guide's 'Install extensions without network connection' section.

## Change and rationale

New skill: diagnose extension installation failures in 3D Slicer.

Extension install failures are one of the most repeated support topics in the Slicer community, and the failure modes have sharply different fixes: a download error needs the offline install flow, a loadSourceAsModule error needs a revision-matched package, and a missing module usually just needs a restart. This skill triages from the observable symptom so agents stop reinstalling Slicer for a network problem.