App installation and permissions
Installation problems are usually the package; runtime problems are usually a capability the workspace cannot provide. The distinction is worth making before you change anything, because they have nothing to do with each other.
Symptoms
- The install button is unavailable, or choosing a package does nothing.
- An install is refused with a manifest, schema or compatibility message.
- An installed app will not launch.
- An app launches but a feature is unavailable — no files, no terminal, no network.
- A permission prompt appears where you did not expect one, or a previously working feature stops after a permission change.
Checks
1. Wait for the catalog. In App Manager, package selection stays disabled until the installed-app catalog has loaded. Acting before it does produces a complaint that the catalog must be loaded first, which clears on refresh — if you see it, refresh and wait for the control to become enabled rather than repeating the action.
2. Check the package, not the app. An app package is validated on install: manifest schema version, identity, declared permissions, declared compatibility with the ShellCanvas client platform, and the files it lists. A package built against a different schema version, or declaring compatibility you do not have, is refused before anything is installed.
3. Check the platform boundary. The app runtime is validated on Windows only. Elsewhere, treat app installation and launch as unverified.
4. Read what the app asked for. Permissions are shown before installation and are exactly what the app may use: file access, console, host settings, storage, network hosts, clipboard, window control, custom services. Nothing is granted implicitly, and there is no way for an app to widen its own grants later.
5. Separate "denied" from "unavailable". Denied means the app holds no grant — a permission decision. Unavailable means the workspace has no connection providing that capability — a binding decision. Granting a permission cannot conjure a capability the host does not offer.
6. For a custom service, check both sides. The app needs a grant for that service id, and the connected adapter must actually advertise it. Grants are per service, so an app with services.com.example.a cannot reach com.example.b.
Resolution
| Situation | What to do |
|---|---|
| Selection disabled | Wait for the catalog to load, or refresh App Manager. |
| Manifest or schema refusal | Rebuild the package against the current schema — see Package and install an app. |
| Compatibility refusal | The package declares a client platform this desktop does not satisfy. Use a build that matches, or update ShellCanvas. |
| App will not launch | Confirm it is enabled, and that nothing about the installed files changed after review. Reinstall from a known package. |
| Feature denied | Review the app's permissions in App Manager and grant what it legitimately needs, or accept the reduced function. |
| Feature unavailable | Bind a connection that provides the capability — see Workspaces and windows. |
| Network request refused | The host is not in the app's approved allowlist. Approve it deliberately, host by host. |
| Storage failure | The app is at its quota. That is a per-app limit, not a disk problem — see Storage API. |
| Permission changed while running | Open windows may stay usable so work can be recovered; new launches respect the new state. Close and relaunch once you are done. |
Do not work around a refusal by bypassing review. Review is the point at which you see what a package contains and what it will be allowed to do; skipping it removes the only safeguard that installation offers.
When to report an issue
Report when an app that satisfies these checks still fails: a valid package refused without a reason you can act on, a granted permission that still produces a denial, a capability the connection advertises that the app cannot reach, or an isolation boundary that does not hold.
Include the ShellCanvas version, your platform, the app's id and version, its declared permissions, which capability failed, and the exact visible message. If the app is your own, include a minimal reproduction package. Keep remote content, credentials and private app storage out of the report.
Related guides
- Install and manage apps — the normal installation path.
- Package and install an app — manifests, permissions and limits.
- Extension permissions and trust — what each grant means.
- App lifecycle and permissions — how grants behave at runtime.