quarkusio/quarkus · error · RuntimeException

Can only sync state on the server side of remote dev mode

Error message

Can only sync state on the server side of remote dev mode

What it means

RuntimeUpdatesProcessor.syncState merges client-side file hashes into the server's state and is only meaningful on the server side of remote dev mode. If the current dev mode is not DevModeType.LOCAL or REMOTE_SERVER_SIDE — specifically anything other than REMOTE_SERVER_SIDE per the guard — it throws a RuntimeException. Calling it on a remote client or offline instance is a programming/lifecycle error.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/dev/RuntimeUpdatesProcessor.java:732

    @Override
    public void addPreRestartStep(Runnable runnable) {
        preRestartSteps.add(runnable);
    }

    @Override
    public void addPostRestartStep(Runnable runnable) {
        postRestartSteps.add(runnable);
    }

    @Override
    public void consumeNoRestartChanges(Consumer<Set<String>> consumer) {
        noRestartChangesConsumers.add(consumer);
    }

    @Override
    public Set<String> syncState(Map<String, String> fileHashes) {
        if (getDevModeType() != DevModeType.REMOTE_SERVER_SIDE) {
            throw new RuntimeException("Can only sync state on the server side of remote dev mode");
        }
        Set<String> ret = new HashSet<>();
        try {
            Map<String, String> ourHashes = new HashMap<>(IsolatedRemoteDevModeMain.createHashes(applicationRoot));
            for (Map.Entry<String, String> i : fileHashes.entrySet()) {
                String ours = ourHashes.remove(i.getKey());
                if (!Objects.equals(ours, i.getValue())) {
                    ret.add(i.getKey());
                }
            }
            List<Path> removedFiles = List.of();
            for (Map.Entry<String, String> remaining : ourHashes.entrySet()) {
                String file = remaining.getKey();
                if (file.endsWith("META-INF/MANIFEST.MF") || file.contains("META-INF/maven")
                        || !file.contains("/")) {
                    //we have some filters, for files that we don't want to delete
                    continue;
                }

View on GitHub (pinned to e1c734241f)

Solutions

1. Start the target in remote server-side dev mode (quarkus:dev with remote-dev server configuration, DevModeEntry requiring REMOTE_SERVER_SIDE).
2. Point your sync client at the server-side URL, not a remote-dev client instance.
3. Verify quarkus.remote-dev configuration: client mode instances should push via the client, not call syncState directly.
4. Remove any custom code calling syncState in non-remote-dev runs.

Example fix

// before: client-side instance
// ./mvnw quarkus:remote-dev (client) then POST to its own syncState -> throws
// after: run server side first
// server: ./mvnw quarkus:dev -Dquarkus.launch.devmode=true (server-side remote)
// client: ./mvnw quarkus:remote-dev -Dquarkus.remote-dev.url=http://server:8080

if (processor.getDevModeType() != DevModeType.REMOTE_SERVER_SIDE) {
    throw new IllegalStateException("syncState requires the remote-dev SERVER side instance");
}

boolean canSyncState(RuntimeUpdatesProcessor p) {
    return p.getDevModeType() == DevModeType.REMOTE_SERVER_SIDE;
}

try {
    processor.syncState(hashes);
} catch (RuntimeException e) {
    if ("Can only sync state on the server side of remote dev mode".equals(e.getMessage())) {
        log.error("Target is not the remote-dev server — check launch mode and client URL");
    } else throw e;
}

When it happens

Trigger: Calling syncState(fileHashes) when getDevModeType() != DevModeType.REMOTE_SERVER_SIDE — e.g. invoked against a remote-dev client (REMOTE_CLIENT_SIDE) or a plain local dev mode instance not acting as the remote server.

Common situations: Pointing a sync client at the wrong Quarkus instance (client instead of server); starting the server without -Dquarkus.launch.rebuild-all-in-remote-dev... i.e. without remote-server-side dev mode enabled; custom tooling calling syncState outside remote-dev.

Related errors

• remote-dev can only be used with mutable applications i.e. u
• Cannot reset a started application
• Could not connect to remote side after restart
• Live reload URL set but no password, remote dev requires a p
• Unable to deserialize the dev mode context. Does the Quarkus

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/d361d6598d6bc512. Report an issue: GitHub.