xpipe-io/xpipe · error · ValidationException

parentHostDoesNotSupportTunneling

Error message

parentHostDoesNotSupportTunneling

What it means

NetworkTunnelStore.checkTunnelable() validates that a data store's parent host is capable of network tunneling. If the referenced store does not implement NetworkTunnelStore, or the tunnel store itself reports an unsupported parent via getUnsupportedParent(), a ValidationException is thrown with the i18n message 'parentHostDoesNotSupportTunneling'. This guards against configuring tunnel-backed connections on hosts that cannot forward traffic.

Source

Thrown at app/src/main/java/io/xpipe/app/store/NetworkTunnelStore.java:14

package io.xpipe.app.store;

import io.xpipe.app.core.AppI18n;
import io.xpipe.app.storage.DataStoreEntryRef;
import io.xpipe.app.util.HostAddress;
import io.xpipe.app.util.ValidationException;

import java.util.Optional;

public interface NetworkTunnelStore extends DataStore, SelfReferentialStore {

    static void checkTunnelable(DataStoreEntryRef<?> ref) throws ValidationException {
        if (!(ref.getStore() instanceof NetworkTunnelStore t)) {
            throw new ValidationException(
                    AppI18n.get("parentHostDoesNotSupportTunneling", ref.get().getName()));
        }

        var unsupported = t.getUnsupportedParent();
        if (unsupported.isPresent()) {
            throw new ValidationException(AppI18n.get(
                    "parentHostDoesNotSupportTunneling", unsupported.get().get().getName()));
        }
    }

    DataStoreEntryRef<?> getNetworkParent();

    boolean requiresTunnel();

    default HostAddress getTunnelHostName() {
        return HostAddress.empty();
    }

View on GitHub (pinned to d85ca821ba)

Solutions

1. Change the connection's network parent to a host store that implements NetworkTunnelStore (e.g. an SSH connection with forwarding enabled)
2. Enable port forwarding/tunneling on the parent host connection so getUnsupportedParent() returns empty
3. Remove the tunnel parent (use a direct connection) if tunneling is not actually needed
4. Verify with the parent's connection settings that the underlying protocol supports TCP forwarding

Example fix

// before
DataStoreEntryRef<?> ref = entry.ref(); // ref points to a local shell store
NetworkTunnelStore.checkTunnelable(ref); // throws ValidationException
// after
DataStoreEntryRef<?> ref = sshConnectionEntry.ref(); // SSH host supports tunneling
NetworkTunnelStore.checkTunnelable(ref); // passes

static boolean isTunnelableParent(DataStoreEntryRef<?> ref) {
    if (!(ref.getStore() instanceof NetworkTunnelStore t)) return false;
    return t.getUnsupportedParent().isEmpty();
}
// call NetworkTunnelStore.checkTunnelable(ref) only if isTunnelableParent(ref)

boolean ok = ref.getStore() instanceof NetworkTunnelStore t && t.getUnsupportedParent().isEmpty();

When it happens

Trigger: Calling checkTunnelable(DataStoreEntryRef) with (a) a ref whose store does not implement NetworkTunnelStore (line 14), or (b) a NetworkTunnelStore whose getUnsupportedParent() returns a non-empty Optional (line 20), e.g. the parent host entry is a plain shell/serial connection that lacks tunnel support.

Common situations: Selecting a parent host for an SSH-tunnel-backed connection that is itself a local machine, serial connection, or a protocol without port-forwarding; nesting tunnels under a host that disallows forwarding; misconfigured store hierarchy where a non-tunnelable store is set as network parent.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Couldn't send request
• Cannot delete category: " + cat.getName()
• HTTP API is not enabled
• Not a toggleable connection
• Development build launched in wrong working directory, expec

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