Discovery Troubleshooting

Use this guide to diagnose issues with application discovery across all providers (Windows Shortcuts, Windows MSIX/UWP, macOS LaunchServices, Linux Freedesktop, CLI Tools on PATH, Portable Applications, Turbo Workspaces). If apps are discovered but fail to launch, see Applications Troubleshooting.

Quick Checks

• Press F5 in the Applications tab to force a refresh.
• Confirm provider configuration under configuration.discovery.providers.
• Review policy: apps are filtered by allow rules. See Authorization & Visibility.
• Check logs for discovery events and errors. See Log locations.

Verify Provider Configuration

Example (all providers enabled, MSIX prioritized over Shortcuts):

{
  "configuration": {
    "discovery": {
      "providers": [
        { "type": "windows.msix", "enabled": true },
        { "type": "windows.shortcuts", "enabled": true },
        { "type": "macos.launchservices", "enabled": true },
        { "type": "linux.freedesktop", "enabled": true }
      ]
    }
  }
}

• Providers execute in order. Earlier providers win dedupe conflicts.
• Use filters.include / filters.exclude to constrain scope when needed.

Provider‑Specific Diagnostics

Windows Shortcuts (windows.shortcuts)

Symptoms

• Expected Start Menu or Desktop shortcuts are missing.

Checks

• Verify .lnk/.url files exist:
  • Start Menu (User): %APPDATA%\Microsoft\Windows\Start Menu\Programs
  • Start Menu (All Users): %PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs
  • Desktop (User): %USERPROFILE%\Desktop
  • Desktop (Public): %PUBLIC%\Desktop
• Ensure the user has read access to the above paths.
• Open a .lnk and confirm the target path is valid.
• Watchers: heavy filesystem churn may delay updates; press F5 to rescan.

Windows MSIX/UWP (windows.msix)

Symptoms

• Packaged apps not shown under APPS; icons/names incorrect.

Checks

• Confirm the app is present in shell:AppsFolder.
• Ensure the package is installed for the current user (per‑user provisioning).
• Retrieve the AUMID and validate:
  • In PowerShell: (Get-StartApps | Where-Object {$_.Name -like '*AppName*'})
• Re‑register broken packages if needed: Add-AppxPackage -Register against the package manifest.
• Enterprise devices: verify AppX deployment policies and that package catalog APIs are available.

macOS LaunchServices (macos.launchservices)

Symptoms

• Apps under /Applications do not appear or have generic icons.

Checks

• Verify the app exists in /Applications, /System/Applications, or ~/Applications.
• Test activation: open -n -a "App Name" or open -b <CFBundleIdentifier>.
• Rebuild LaunchServices database if stale:
  • /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -kill -r -domain local -domain system -domain user
• Gatekeeper/quarantine can block execution; verify extended attributes.

Linux Freedesktop (linux.freedesktop)

Symptoms

• .desktop entries missing or not launching.

Checks

• Verify files exist:
  • System: /usr/share/applications
  • User: ~/.local/share/applications
• Validate .desktop syntax: desktop-file-validate file.desktop.
• Ensure Name, Exec, and (optionally) Icon are set. Prefer absolute paths in Exec.
• Respect NoDisplay/Hidden; entries with NoDisplay=true or Hidden=true are typically not shown.

CLI Tools on PATH (cli.path)

Symptoms

• Expected CLI tools (e.g., git, node, kubectl, python) are missing from the CLI TOOLS group.

Checks

• Verify PATH seen by the Launcher process includes the expected directories.
  • Windows (PowerShell): $env:PATH -split ';'
  • macOS/Linux: echo $PATH | tr ':' '\n'
• If tools live outside PATH, add them via provider options.includePaths.
• Confirm provider filters and options:
  • filters.include/filters.exclude patterns match the tool names or resolved paths.
  • Signature/publisher gating not excluding the binaries (Windows/macOS code signing).
• Resolve actual binary path and test execution:
  • Windows: where.exe git
  • macOS/Linux: which git
• Reorder providers or refresh (F5) if dedupe preferred a different source.

Portable Applications (portable.apps)

Symptoms

• Expected apps in PORTABLE APPS are missing or not updating from network shares.

Checks

• Ensure options.scanRoots paths exist and are accessible by the current user.
• For network shares, the UNC/NFS path must be in options.uncAllowlist and reachable.
• Confirm file types are permitted by options.allowedExtensions and within options.maxDepth.
• Signature/publisher gating may filter unsigned binaries if requireSigned=true.
• Large directories or offline shares: press F5 to force a rescan; watchers may not track remote filesystems.
• On Windows Secure Sandbox deployments, portable roots on non‑NTFS or disallowed volumes may be gated by policy. See Authorization & Visibility and Runtime.

Turbo Workspaces (turbo.workspaces)

Symptoms

• WORKSPACES group is empty or missing expected workspace applications.

Checks

• Sign in and trust the target domain(s); verify connectivity to the Portal/Hub.
• Verify the user has entitlement to the workspace/app and that options.includeWorkspaces does not filter it out.
• Offline behavior is controlled by options.offlineMode:
  • subscribedOnly: shows locally subscribed workspaces only
  • hideAll: hides entries while offline
  • showCached: shows cached catalog entries
• If duplicates appear with local sources, adjust provider ordering or use filters.exclude.
• Proxy environments: confirm proxy settings; see Proxy Settings documentation.

Deduplication Conflicts (Duplicates/Missing)

• Symptom: an app appears twice or the shortcut appears instead of the richer MSIX entry.
• Fix: reorder providers so the preferred source comes first, or use filters.exclude to suppress duplicates.

Icons and Metadata

• Windows MSIX/UWP: icons and names come from AppxManifest; stale cache may require a refresh.
• macOS: CFBundleIcon and localized names from Info.plist. If icons are missing, open the app once to warm caches or rebuild LaunchServices.
• Linux: the Icon key should be the theme name or absolute path; verify the icon theme is installed.

Performance and Scale

• Large Start Menu trees or application directories can cause initial scans to take longer; the UI remains usable.
• If file watcher limits are reached (rare), background reconciliation ensures eventual consistency.

Related

• Application Discovery
• Applications Troubleshooting
• Authorization & Visibility
• Log Locations