xpipe-io/xpipe · critical · IllegalStateException

Required local XPipe installation was not found but is requi

Error message

Required local XPipe installation was not found but is required for development. See https://github.com/xpipe-io/xpipe/blob/master/CONTRIBUTING.md#development-setup

What it means

During extension discovery in development mode, XPipe requires a locally installed XPipe build to supply external modules. If AppInstallation.ofDefault() points to a non-existent base path, findAndParseExtension aborts with an IllegalStateException linking the contributing guide.

Source

Thrown at app/src/main/java/io/xpipe/app/core/AppExtensionManager.java:130

                    extendedLayer.findModule(AppNames.extModuleName("proc")).orElseThrow());
        }
    }

    private Optional<Module> findAndParseExtension(String name, ModuleLayer parent) {
        var inModulePath = ModuleLayer.boot().findModule(AppNames.extModuleName(name));
        if (inModulePath.isPresent()) {
            TrackEvent.info("Loaded extension " + name + " from boot module path");
            return inModulePath;
        }

        if (!AppProperties.get().isFullVersion()) {
            try {
                if (externalModuleFileSystem == null) {
                    var localInstallation =
                            AppInstallation.ofDefault(AppProperties.get().isLocatePtb());
                    Path p = localInstallation.getBaseInstallationPath();
                    if (!Files.exists(p)) {
                        throw new IllegalStateException(
                                "Required local " + AppNames.ofCurrent().getName()
                                        + " installation was not found but is required for development. See https://github"
                                        + ".com/xpipe-io/xpipe/blob/master/CONTRIBUTING.md#development-setup");
                    }

                    if (AppProperties.get().isLocatorVersionCheck()) {
                        var iv = getLocalInstallVersion(localInstallation);
                        var installVersion = AppVersion.parse(iv)
                                .orElseThrow(() -> new IllegalArgumentException("Invalid installation version: " + iv));
                        var sv = !AppProperties.get().isImage()
                                ? Files.readString(Path.of("version")).strip()
                                : AppProperties.get().getVersion();
                        var sourceVersion = AppVersion.parse(sv)
                                .orElseThrow(() -> new IllegalArgumentException("Invalid source version: " + sv));
                        if (!installVersion.equals(sourceVersion)) {
                            throw new IllegalStateException("Incompatible development version. Source: " + sv
                                    + ", Installation: "
                                    + iv

View on GitHub (pinned to d85ca821ba)

Solutions

1. Install the XPipe desktop application locally (see CONTRIBUTING.md development setup)
2. Ensure the installation is at the default location AppInstallation.ofDefault() resolves to
3. Check AppProperties locator/PTB flags are not pointing at a missing variant
4. Re-run the app after installation so externalModuleFileSystem can be populated

Example fix

// before
./gradlew run // fails: no local installation
// after
// install XPipe first, e.g. via package manager or installer script, then
./gradlew run

const fs = require('fs');
function assertLocalXpipeInstalled(installPath) {
  if (!fs.existsSync(installPath)) {
    throw new Error(`Local XPipe installation missing at ${installPath}; install it before running dev mode`);
  }
}

try {
  app.bootstrap(); // triggers extension discovery
} catch (e) {
  if (String(e.message).includes('Required local')) {
    console.error('Install the XPipe desktop app per CONTRIBUTING.md, then re-run.');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Running the XPipe application from source in a development environment without a local XPipe installation present at the default installation location.

Common situations: Fresh clone of the repo without ever installing the XPipe desktop app, custom install location not detected, or PTB/locator settings changing which install path is resolved.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

AI-assisted analysis of xpipe-io/xpipe@d85ca821ba (2026-09-06). Data as JSON: /api/errors/d29500a95794fabb. Report an issue: GitHub.