xpipe-io/xpipe · error · RuntimeException

Unable to set up scripts

Error message

Unable to set up scripts

What it means

ScriptStoreSetup.controlWithScripts() wraps script initialization (initScriptsDirectory and applying each script ref) and rethrows any Throwable as RuntimeException("Unable to set up scripts", t). A StackOverflowError is specially converted to an 'expected' error hinting at circular script dependencies. This error means the shell setup phase could not install/apply the configured scripts.

Source

Thrown at ext/base/src/main/java/io/xpipe/ext/base/script/ScriptStoreSetup.java:109

                                }

                                return Optional.ofNullable(shellControl
                                        .getShellDialect()
                                        .addToPathVariableCommand(List.of(dir.toString()), true));
                            }

                            @Override
                            public boolean canPotentiallyRunInDialect(ShellDialect dialect) {
                                return true;
                            }
                        },
                        append);
            }
        } catch (StackOverflowError t) {
            throw ErrorEventFactory.expected(
                    new RuntimeException("Unable to set up scripts. Is there a circular script dependency?", t));
        } catch (Throwable t) {
            throw new RuntimeException("Unable to set up scripts", t);
        }
    }

    @SneakyThrows
    private static FilePath initScriptsDirectory(ShellControl sc, List<DataStoreEntryRef<ScriptStore>> refs) {
        if (refs.isEmpty()) {
            return null;
        }

        var applicable =
                refs.stream().filter(ss -> ss.getStore().isCompatible(sc)).toList();
        if (applicable.isEmpty()) {
            return null;
        }

        var hash = refs.stream()
                .mapToInt(value ->
                        value.get().getName().hashCode() + value.getStore().hashCode())

View on GitHub (pinned to d85ca821ba)

Solutions

  1. Inspect the cause (getCause()) to find the real failure; for StackOverflowError, look for circular script dependencies and remove the self/cross reference
  2. Validate each referenced ScriptStore with checkComplete() before connecting
  3. Verify the shell connection and permissions for creating the scripts directory on the target machine
  4. Temporarily remove script references from the connection to isolate the failing script

Example fix

// before (circular)
scriptA.getScripts().add(refOf(scriptA));
// after
// reference a different script, or remove the self-reference
scriptA.getScripts().remove(refOf(scriptA));
Defensive patterns

Strategy: try-catch

Validate before calling

// before connecting
for (var ref : scriptRefs) {
    ref.getStore().checkComplete(); // fail fast on broken scripts
}

Try / catch

try {
    controlWithDefaultScripts(sc);
} catch (RuntimeException e) {
    Throwable c = e.getCause();
    if (c instanceof StackOverflowError) {
        // circular script dependency: inspect script reference graph
    }
}

Prevention

When it happens

Trigger: Calling controlWithScripts/controlWithDefaultScripts for a connection whose script references fail: initScriptsDirectory throws (shell/directory problems), a script's apply step throws, or a StackOverflowError occurs from a script depending on itself (circular ScriptStore reference chain).

Common situations: Circular script dependency (script A references script B which references A) causing StackOverflowError; a referenced script store is broken or empty; shell connection fails while creating the scripts directory; permission problems creating init scripts on the remote machine.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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