[Bug]: App - CommandLine.addArguments() handleQuoting breaks App.open() when arguments contain spaces

[adriancostin6]

Summary

When I try opening my Oculix App, CommandLine messes up the quoting that reaches ProcessBuilder and the App fails to open. A reproducer is included in the Additional context section.

Steps to reproduce

1. Set up the reproducer below on your Linux machine
2. Run the run.sh reproducer script provided in Additional context

Expected behavior

App opens without having to do dirty tricks behind the scenes to disable handleQuoting.

Actual behavior

App does not open, I have to do reflection to disable the quoting to make it open.

Minimal reproducer (script)

Operating system

Ubuntu / Debian

Java version

openjdk 21.0.9 2025-10-21 LTS

OculiX version / artifact

oculixapi-3.0.3-rc4-linux.jar

Where does the bug happen?

API (Screen / Region / Pattern / Match)

Logs / console output

Additional context

handleQuoting defaults to true when we call addArguments(String) in the Oculix App constructor:

Oculix/API/src/main/java/org/sikuli/script/App.java

Line 147 in e9d572c

cmd.addArguments(arguments);

This, in turn leads to broken handling of quoting before passing certain commands to process builder. In my use-case, I could reproduce this fairly easily.

I have created a small reproducer for the handleQuoting problem. The main components of this are:

• Simple.java: A small Java application that spawns a Swing GUI when a file is passed as an argument
• SImpleProcessBuilder.java: Uses process builder to start the Simple.java program using java, passing a file as an argument
• SimpleOculixApp.java: Uses the Oculix API to start the same Simple.java program using java, passing a file as an argument
• run.sh: shell script that automates building and running the reproducer. this compiles and bundles Simple.java as a jar, then downloads the Oculix API RC4 for Linux and runs SimpleProcessBuilder.java, SimpleOculixApp and SimpleOculixApp + reflection enabled via a CLI parameter. it should handle everything, but feel free to adapt if it breaks on your machine.

As stated above, the Java classes for SimpleOculixApp and SimpleProcessBuilder start the Simple.java program using the created JAR. They do so using java, so make sure that it is in PATH and ready to go.

That being said, the runner script creates a directory that contains spaces in the path to trigger the BUG. It moves the created JAR file there, and creates an extra argfile and a dummy file. These will be later used as arguments to the java command that will run SimpleOculixApp and SimpleProcessBuilder to match my exact use-case. By doing so, I hoped to highlight the way in which handleQuoting will prevent apps from opening when hitting this scenario.

I will attach the reproducer files below, but also paste them as code-blocks, in case one is easier to use than the other.

SimpleProcessBuilder.java
Simple.java
SimpleOculixApp.java
run.sh

#!/usr/bin/env bash

# run.sh

cleanup() {
    rm -f manifest.mf
    rm -f *.jar
    rm -f *.class
    rm -rf "spa ces"
}
trap "cleanup" EXIT

mkdir -p "spa ces"
echo "--add-opens=java.base/java.io=ALL-UNNAMED" >> "spa ces/some.argfile"
echo "bla bla bla" > "spa ces/some.file"

# Step 1. Compile a simple java JAR with a Swing app
echo "Compiling a simple Swing app, used for testing..."
javac Simple.java
echo "Main-Class: Simple" > manifest.mf
jar -cvmf manifest.mf simple.jar Simple.class
mv simple.jar "spa ces"

# Step 2. Get Oculix API and compile the reproducer
# Start SimpleProcessBuilder
echo "Running SimpleProcessBuilder..."
echo "Proves that passing arguments even with no quoting as cmd array works."
javac SimpleProcessBuilder.java
java -cp . SimpleProcessBuilder # should open app just fine
## Start SimpleOculixApp
wget https://github.com/oculix-org/Oculix/releases/download/v3.0.3-rc4/oculixapi-3.0.3-rc4-linux.jar
javac -cp oculixapi-3.0.3-rc4-linux.jar SimpleOculixApp.java
echo "Running SimpleOculixApp without reflection..."
echo "Proves that the app won't open due to broken handleQuoting."
java -cp ".:oculixapi-3.0.3-rc4-linux.jar" SimpleOculixApp
echo "Running SimpleOculixApp with reflection to disable broken handleQuoting..."
echo "Proves that app opens if we do manual quoting for parameters instead of handleQuoting."
java -cp ".:oculixapi-3.0.3-rc4-linux.jar" SimpleOculixApp dirtyReflection

import javax.swing.*;
import java.awt.*;
import java.io.File;

// Simple.java

public class Simple {
    public static void main(String[] args) {
        System.out.println("Argument count: " + args.length);
        for (int i = 0; i < args.length; i++) {
            System.out.println("Argument " + i + ": " + args[i]);
        }

        String guiUnlocker = args[0];
        File f = new File(guiUnlocker);
        if(f.isFile()) { 
            System.out.println("File found, opening GUI.");

            JFrame frame = new JFrame("Simple");
            frame.setPreferredSize(new Dimension(1000, 800));

            JPanel panel = new JPanel();
            JLabel label = new JLabel("Hello, World!");
            panel.add(label);
            frame.add(panel);

            frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
            frame.pack();
            frame.setLocationRelativeTo(null);
            frame.setVisible(true);
        } else {
            System.out.println("File not found, no GUI for you.");
        }

    }
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;

// SimpleProcessBuilder.java

public class SimpleProcessBuilder {
    public static void main(String[] args) {
        ProcessBuilder pb = new ProcessBuilder(
                "java",
                "@spa ces/some.argfile",
                "-cp",
                "spa ces/simple.jar",
                "Simple",
                "spa ces/some.file"
        );

        // Merge stderr into stdout so we capture both
        pb.redirectErrorStream(true);

        try {
            Process process = pb.start();

            // Read and print all output
            try (BufferedReader reader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
                String line;
                while ((line = reader.readLine()) != null) {
                    System.out.println(line);
                }
            }

            // Wait for process to complete and get exit code
            int exitCode = process.waitFor();
            System.out.println("Process exited with code: " + exitCode);
        } catch (IOException | InterruptedException e) {
            System.err.println("IOException: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

import org.sikuli.script.App;

import org.apache.commons.exec.CommandLine;
import java.lang.reflect.Field;
import java.util.List;

// SimpleOculixApp.java

public class SimpleOculixApp {
    public static void main(String[] args) {
        App app = new App(
            "java",
            "\"@spa ces/some.argfile\" -cp \"spa ces/simple.jar\" Simple \"spa ces/some.file\""
        );

        if (args.length > 0) {
            System.out.println("Using reflection to disable handleQuoting...");
            try {
                Field cmdField = app.getClass().getDeclaredField("cmd");
                cmdField.setAccessible(true);
                CommandLine commandLine = (CommandLine) cmdField.get(app);
                Field argumentsField = commandLine.getClass().getDeclaredField("arguments");
                argumentsField.setAccessible(true);
                List<Object> arguments = (List<Object>) argumentsField.get(commandLine);
                for (Object argument : arguments) {
                    Field handleQuotingField = argument.getClass().getDeclaredField("handleQuoting");
                    handleQuotingField.setAccessible(true);
                    handleQuotingField.set(argument, Boolean.FALSE);
                }
            } catch (NoSuchFieldException | IllegalAccessException e) {
                throw new RuntimeException(e);
            }
        }

        app.reset();
        if(app.open()) {
            System.out.println("App opened successfully");
        } else {
            System.out.println("Failed to open app");
        }
    }
}

[julienmerconsulting]

@adriancostin6 — third surgical-grade report in two weeks 💎. The reflection workaround included as a third comparison column is the kind of move that turns a bug report into a debugger's confession. Confirmed end-to-end on RC4, and your call site shouldn't have to use reflection — that's on us, not on you.

🔬 What I reproduced on oculixapi-3.0.3-rc4-linux.jar

Your repro, on a fresh box, with one twist: I replaced java with a wrapper script that logs its received argv to a file, so we can see literally what ProcessBuilder sent to the child. No room for interpretation:

Case	argv received by child
OculiX RC4 default (handleQuoting=true)	["@spa ces/some.argfile"] [-cp] ["spa ces/simple.jar"] [Simple] ["spa ces/some.file"]
OculiX RC4 + your reflection trick (handleQuoting=false)	[@spa ces/some.argfile] [-cp] [spa ces/simple.jar] [Simple] [spa ces/some.file]

The literal " characters survive into argv in the default case. The child JVM dutifully looks for a file named "@spa ces/some.argfile" with the quotes, fails, exits, app never opens. Your diagnosis is exact.

Bytecode confirmation on the same RC4 jar — App.class calls the 1-arg signature CommandLine.addArguments(Ljava/lang/String;), which means handleQuoting=true by default. You pointed at App.java:147, and that's exactly the line.

🤔 Wait — didn't #191 fix this?

Fair question, and I want to address it head-on because the timeline is instructive.

Version	Pipeline	What it covered
Pre-#191	cmd = CommandLine.parse(name); — single call, parses executable + args together	None of this. Quotes around the executable were eaten.
Post-#191 (current RC4)	cmd = new CommandLine(executable); then cmd.addArguments(arguments);	Executable path is safe. Arguments still go through Commons Exec's quoting.

#191 split the pipe into two halves and fixed the left half (executable). The right half (arguments) inherited the same Commons-Exec-knows-best philosophy, just one method call lower. The test matrix on #191 — your initial repro, RaiMan's macOS check, the error=2 follow-up — all stressed the executable path. Nobody pushed a realistic case with quoted arguments containing spaces until you did, with this issue. So the bug was sitting there, dormant, on the right half of the pipe.

In short: #191 was correct for what it tested. It just didn't test enough. You did. 🎯

💭 Why I'm not going to "fix it with handleQuoting=false" alone

The temptation is: change line 147 to cmd.addArguments(arguments, false) and call it a day. I want to explain why this is a trap, because it pre-empts a follow-up issue you'd reasonably file two weeks from now.

handleQuoting=false doesn't strip quotes — it just stops Commons Exec from being quote-aware at all, including for tokenization. Your input becomes naively split on whitespace:

"@spa ces/some.argfile -cp spa ces/simple.jar Simple spa ces/some.file"
       ↓ split on whitespace, no quote awareness
[@spa, ces/some.argfile, -cp, spa, ces/simple.jar, Simple, spa, ces/some.file]

Eight tokens instead of five — you'd lose your spaces-in-paths in a different way. There is no value of handleQuoting, alone, that gets you what ProcessBuilder would have given you natively. The single-String arguments API is structurally lossy when arguments contain spaces — any escape convention (quotes, backslashes, commas…) requires a faithful round-trip parser, and Commons Exec's parser doesn't do it.

So we need to leave the String API behind for cases like yours, not patch it.

🛠️ The plan for v3.0.4 — strict core + opt-in sugar

Following the same shape every modern process API has converged on (ProcessBuilder, Python subprocess, Node child_process, Go os/exec, Rust Command), the canonical surface becomes a String[] overload — no parsing, no ambiguity, one element per argv:

// 🟢 Canonical — what your reproducer needs and what prod call sites should use
public App(String executable, String[] arguments)
public App setArguments(String[] arguments)

Your call site collapses to:

new App("java", new String[]{
    "@spa ces/some.argfile",
    "-cp", "spa ces/simple.jar",
    "Simple",
    "spa ces/some.file"
});

No quotes. No reflection. Goes directly into a ProcessBuilder String[] with zero re-tokenization. Same contract as your SimpleProcessBuilder baseline — which, not coincidentally, is the one that worked.

For users who explicitly want the convenience of "one string with my chosen convention", small opt-in helpers with documented rules (rather than a permissive guess-the-format mega-parser, which becomes a Norway-problem factory):

// 🟡 Existing — kept for backwards-compat, no behaviour change
new App("java", "-cp foo.jar Main");          // safe when no embedded spaces

// 🟢 Opt-in helpers, each with one documented convention
App.shellArgs("\"foo bar\" -cp baz");          // POSIX-style: quotes group, \ escapes
App.csvArgs("@spa ces/argfile,-cp,spa ces/jar,Simple,spa ces/file");  // commas group, \ escapes

Each helper returns a String[] you feed back into the canonical constructor — so the parser surface stays small, opt-in, and per-style testable. No telepathic "guess what format the user picked" logic anywhere.

🚦 Diff summary

Path	Behaviour pre-RC4	RC4 (now, broken on your case)	v3.0.4 (planned)
App(String, String) with no embedded spaces	✅	✅	✅ (kept)
App(String, String) with quoted spaces	❌ (#191 bug)	❌ (this issue)	🟡 still String-API limitations, documented; helpers preferred
App(String, String[])	—	—	✅ new — your case becomes 1-liner
App.shellArgs(...) / App.csvArgs(...)	—	—	✅ new — explicit convention helpers
Reflection workaround needed	—	yes 😞	no, never

🚦 Next step

I'll cut the String[] overload + the two helpers on a branch, with a unit test built directly on your repro (spa ces/... paths, @argfile, -cp, the lot). The reproducer you shipped is now part of the regression suite — exactly like your Ubuntu 24 Dockerfile became the canonical OCR check on #211. Your bug, your test, locked in. 🔒

Will ping you here once the RC is up. Optional: if you want to adopt the new String[] API early on a branch and confirm your prod use case is unblocked without reflection, I'll cut you a snapshot.

Thanks again for the diamond-tier report 💎. Three for three. Adrian Pattern™ now formally adopted at OculiX: "Always include the workaround. Especially if it's reflection. Especially especially if it proves the diagnosis."

—

🪦 RIP the single-String arguments-with-quotes API as a precondition (2010 — 2026) — faithful, well-meaning, defeated by ProcessBuilder once and for all.

       .--.
      |o_o |    "From a String to a String[] —
      |:_/ |     no quotes, no reflection,
     //   \ \    no telepathy."
    (|     | )
   /'\_   _/`\
   \___)=(___/

   ProcessBuilder + Adrian's repro validated together ✓

[adriancostin6]

Thanks @julienmerconsulting for the quick fix. 🥳
As stated, will test it and come back with feedback (either when the RC hits, or some time today with the branch you added it to).

[adriancostin6]

@julienmerconsulting built and tested the fix on branch claude/fix-issue-230-handlequoting. works great ✅ many thanks!

[julienmerconsulting]

@adriancostin6 — green light noted, locking it in. ✅

🚢 What's shipping

Branch claude/fix-issue-230-handlequoting lands as part of v3.0.3-RC5. Concretely:

Surface	State in RC4	State in RC5
App(String executable)	✅ kept	✅ unchanged
App(String executable, String arguments)	⚠️ broken on quoted spaces	⚠️ kept for compat, same caveat (documented)
App(String executable, String[] arguments)	—	🟢 new — your case, zero reflection
App.setArguments(String[])	—	🟢 new — symmetry with the constructor
Reflection workaround needed for spaces-in-paths	yes 😞	never again

The internal pipe is now new CommandLine(executable) + addArgument(arg, false) per element — no addArguments(String), no Commons-Exec re-tokenization, one element of your String[] becomes exactly one element of argv. Same shape ProcessBuilder would have given you natively.

🔒 Regression lock

Your repro from this issue (@spa ces/argfile, -cp, spa ces/simple.jar, Simple, spa ces/some.file) is now a parametrized JUnit case in AppArgumentsTest, asserting on the argv actually received by the child process — exactly the same wrapper-script harness I used to confirm the bug on RC4. Future regressions will trip on your scenario, by name.

Adrian Pattern™ unbroken: bug → repro → workaround that proves the diagnosis → test case named after you. Three for three. 💎

📅 Release timing

RC5 builds are queued behind two other unrelated fixes already on master; ETA mid-week, I'll ping the release thread when the artifact hits Maven Central. If anything shifts in your prod use case in the meantime — even something tangential — drop a note here, easier to fold a sibling fix into the same RC than to chase it after.

🙏 Tip of the hat

Three surgical-grade reports in two weeks, all closed, all promoted to permanent regression tests. This is the kind of contributor history that directly shapes the v3.x stability story — and I'll say so explicitly in the 3.0.3 release notes:

#230 — App.open() corrupts quoted arguments — reported, reproduced and verified by @adriancostin6 (third diamond-tier report on this release cycle)

Closing now. Door stays open for the next one whenever you find it. 🎯

—

🪦 RIP "users must use reflection to bypass our quoting" (RC1 — RC4) — survived by a clean String[] API and a regression test that knows your name.

       .--.
      |o_o |    "argv now arrives
      |:_/ |     exactly as typed —
     //   \ \    no quotes,
    (|     | )   no reflection,
   /'\_   _/`\   no telepathy."
   \___)=(___/

   v3.0.3-RC5 — Adrian-validated ✓