xpipe-io/xpipe · error · IllegalArgumentException

Development build launched in wrong working directory, expec

Error message

Development build launched in wrong working directory, expected project root but got ${cwd}

What it means

In development mode (not a packaged image), XPipe expects to be launched with the working directory set to the project root, verified by the presence of the 'app' and 'lang' directories. If those directories are not under the current working directory, it cannot resolve resources and throws. This is a launch-environment sanity check in determineCurrentInstallationBasePath.

Source

Thrown at app/src/main/java/io/xpipe/app/core/AppInstallation.java:125

        // Resolve any possible links to a real path
        Path path = toRealPathIfPossible(Path.of(command.get()));
        // Check if the process was started using a relative path, and adapt it if necessary
        if (!path.isAbsolute()) {
            path = toRealPathIfPossible(Path.of(System.getProperty("user.dir")).resolve(path));
        }

        var name = path.getFileName().toString();
        // Check if we launched the JVM via a start script instead of the native executable
        if (name.endsWith("java") || name.endsWith("java.exe")) {
            // If we are not an image, we are probably running in a development environment where we want to use the
            // working directory
            var isImage = AppProperties.get().isImage();
            if (!isImage) {
                var cwd = toRealPathIfPossible(Path.of(System.getProperty("user.dir")));
                var valid = Files.exists(cwd.resolve("app")) && Files.exists(cwd.resolve("lang"));
                if (!valid) {
                    throw new IllegalArgumentException(
                            "Development build launched in wrong working directory, expected project root but got "
                                    + cwd);
                }
                return cwd;
            }
            return getInstallationBasePathForJavaExecutable(path);
        } else {
            var dir = getInstallationBasePathForLauncherExecutable(path);
            return toRealPathIfPossible(dir);
        }
    }

    private static Path getInstallationBasePathForLauncherExecutable(Path executable) {
        // Resolve root path of installation relative to executable in a JPackage installation
        return switch (OsType.ofLocal()) {
            case OsType.Linux ignored -> {
                yield executable.getParent().getParent();
            }

View on GitHub (pinned to d85ca821ba)

Solutions

  1. Set the working directory to the project root before launching (IDE run configuration 'Working directory' field)
  2. If using Gradle, run via the provided run task which sets cwd correctly
  3. Verify cwd contains both 'app' and 'lang' directories before launching

Example fix

// before (IDE run config)
Working directory: $HOME
// after
Working directory: $PROJECT_DIR$
Defensive patterns

Strategy: validation

Validate before calling

var cwd = Path.of(System.getProperty("user.dir"));
if (!(Files.exists(cwd.resolve("app")) && Files.exists(cwd.resolve("lang")))) {
    throw new IllegalStateException("Launch from project root, got: " + cwd);
}

Try / catch

try { launch(args); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Development build launched in wrong working directory")) { System.err.println("cd to project root and relaunch"); } else throw e; }

Prevention

When it happens

Trigger: Starting the app in development mode (isImage() == false) from any directory other than the project root, on Windows/Linux/macOS via determineCurrentInstallationBasePath.

Common situations: Running the main class from an IDE whose working directory defaults to the project subdir or $HOME; launching via a script from the wrong cwd; running from inside app/ or a build directory.

Related errors

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