xpipe-io/xpipe · error · IllegalStateException

Incompatible development version. Source: ${source}, Install

Error message

Incompatible development version. Source: ${source}, Installation: ${install}

Please try to check out the matching release version in the repository. See https://github.com/xpipe-io/xpipe/blob/master/CONTRIBUTING.md#development-setup

What it means

XPipe throws this when a development (non-packaged image) build is run and the version file in the checked-out source repository does not match the version the installed extension bundle was built for. It guards against running a mismatched dev source tree against prebuilt extension artifacts. The message directs developers to check out the release tag matching their installation.

Source

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

                    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
                                    + "\n\nPlease try to check out the matching release version in the repository. See https://github"
                                    + ".com/xpipe-io/xpipe/blob/master/CONTRIBUTING.md#development-setup");
                        }
                    }

                    externalModuleFileSystem = FileSystems.newFileSystem(
                            URI.create("jrt:/"),
                            Map.of(
                                    "java.home",
                                    localInstallation.getRuntimePath().toString()));
                }

                var moduleName = "io.xpipe.ext." + name;
                var basePath = externalModuleFileSystem.getPath("modules", moduleName);
                var found = parseExtensionDirectory(basePath, parent);
                if (found.isPresent()) {

View on GitHub (pinned to d85ca821ba)

Solutions

1. Check out the git tag/release matching the installed version (see CONTRIBUTING.md development-setup section)
2. Rebuild the installation so its version matches the source 'version' file
3. Update the local 'version' file only if you intentionally align with the installed build
4. Run a clean build to remove stale artifacts from the previous version

Example fix

// before
git checkout master   # version file says 1.2.3, installation is 1.2.2
// after
git checkout 1.2.2    # or rebuild the installation from current source

var src = Files.readString(Path.of("version")).strip();
if (!src.equals(AppProperties.get().getVersion())) {
    throw new IllegalStateException("Checkout version " + src + " != installed " + AppProperties.get().getVersion());
}

try { extManager.extension(...); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Incompatible development version")) { /* rebuild or checkout matching tag */ } else throw e; }

When it happens

Trigger: Running the app from source (AppProperties.isImage() == false) via findAndParseExtension: the 'version' file in the repo root is parsed and compared to the installation's version; any inequality throws.

Common situations: Developer checked out master/main after a release bump while still using extensions installed from an older release; stale local build artifacts from a previous version; forgot to run the build step that regenerates the version file.

Related errors

• Development build launched in wrong working directory, expec

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