JavaFX 21 + NetBeans 25 + JDK 17: Working Solution and Possible Bug

### Apache NetBeans version

Apache NetBeans 25

### What happened

Hi everyone,

Over the past few days, I spent quite some time trying to get **JavaFX 21** working correctly on **NetBeans 25** with **JDK 17**. I encountered a frustrating issue where, despite setting everything up manually in the project properties, the IDE consistently failed to locate the JavaFX modules at runtime.

I’d like to share a workaround that **finally worked**, and I believe this might point to a **bug or undocumented behavior** in the way NetBeans handles library/module paths.

---

### ? What did *not* work:
Inside the project properties:
- In **Libraries > Compile**, I manually added the required JARs from the JavaFX `lib` folder.
- In **Libraries > Run**, I repeated the same setup.
- In **Run > VM Options**, I added:
```bash
--module-path "C:\path\to\javafx\lib" --add-modules=javafx.controls,javafx.fxml
```

Despite this, the application always failed to locate the **last module** listed in the `--add-modules` flag. I double-checked everything, but no success.

---

### ? What *did* work: Using the Ant Library Manager

Instead of referencing the JARs directly in the project properties, I did the following:

1. **Created a library** using NetBeans' built-in manager:
- Menu: `Tools > Libraries`
- Clicked **New Library**
- Gave it a name (e.g., `JavaFX21Lib`), left the type as `Class Libraries`
- Clicked **Add JAR/Folder** and selected all necessary JARs from the JavaFX 21 `lib` folder
- Clicked **OK**

2. **Referenced this library** in the project:
- Opened Project Properties
- In **Libraries > Compile**, clicked **Add Library** and chose the one I created
- In **Libraries > Run**, repeated the same process

3. **Updated the VM Options**:
- In **Run > VM Options**, added:
```bash
--module-path "C:\path\to\javafx\lib" --add-modules=javafx.controls,javafx.fxml
```

Now, everything works perfectly.

---

** My hypothesis:
It seems that mixing **direct JAR references** with **module-path based VM options** creates a conflict. Possibly, the NetBeans compiler or runtime isn't resolving the paths properly unless the libraries are registered through the Ant Library Manager. Either this is an internal limitation or **an undocumented expectation**.

At best, it's a usability issue — at worst, a bug.

---

* Suggested improvement:
It would be very helpful if:
- This behavior was documented clearly in the NetBeans guide for JavaFX
- A warning or validation existed when conflicting configurations are present
- Or, ideally, NetBeans handles both manual and library-based configurations consistently

---

Hope this helps others facing the same issue. If anyone from the development team is around, I’d be happy to share logs or test further!

Thanks!

### Language / Project Type / NetBeans Component

_No response_

### How to reproduce

Hi everyone,

Over the past few days, I spent quite some time trying to get **JavaFX 21** working correctly on **NetBeans 25** with **JDK 17**. I encountered a frustrating issue where, despite setting everything up manually in the project properties, the IDE consistently failed to locate the JavaFX modules at runtime.

I’d like to share a workaround that **finally worked**, and I believe this might point to a **bug or undocumented behavior** in the way NetBeans handles library/module paths.

---

### ? What did *not* work:
Inside the project properties:
- In **Libraries > Compile**, I manually added the required JARs from the JavaFX `lib` folder.
- In **Libraries > Run**, I repeated the same setup.
- In **Run > VM Options**, I added:
```bash
--module-path "C:\path\to\javafx\lib" --add-modules=javafx.controls,javafx.fxml
```

Despite this, the application always failed to locate the **last module** listed in the `--add-modules` flag. I double-checked everything, but no success.

---

### ? What *did* work: Using the Ant Library Manager

Instead of referencing the JARs directly in the project properties, I did the following:

1. **Created a library** using NetBeans' built-in manager:
- Menu: `Tools > Libraries`
- Clicked **New Library**
- Gave it a name (e.g., `JavaFX21Lib`), left the type as `Class Libraries`
- Clicked **Add JAR/Folder** and selected all necessary JARs from the JavaFX 21 `lib` folder
- Clicked **OK**

2. **Referenced this library** in the project:
- Opened Project Properties
- In **Libraries > Compile**, clicked **Add Library** and chose the one I created
- In **Libraries > Run**, repeated the same process

3. **Updated the VM Options**:
- In **Run > VM Options**, added:
```bash
--module-path "C:\path\to\javafx\lib" --add-modules=javafx.controls,javafx.fxml
```

Now, everything works perfectly.

---

### ?? My hypothesis:
It seems that mixing **direct JAR references** with **module-path based VM options** creates a conflict. Possibly, the NetBeans compiler or runtime isn't resolving the paths properly unless the libraries are registered through the Ant Library Manager. Either this is an internal limitation or **an undocumented expectation**.

At best, it's a usability issue — at worst, a bug.

---

### ?? Suggested improvement:
It would be very helpful if:
- This behavior was documented clearly in the NetBeans guide for JavaFX
- A warning or validation existed when conflicting configurations are present
- Or, ideally, NetBeans handles both manual and library-based configurations consistently

---

Hope this helps others facing the same issue. If anyone from the development team is around, I’d be happy to share logs or test further!

Thanks!

### Did this work correctly in an earlier version?

Apache NetBeans 25

### Operating System

windows 10

### JDK

jdk 17

### Apache NetBeans packaging

Apache NetBeans platform

### Anything else

_No response_

### Are you willing to submit a pull request?

No

Start by reproducing the configuration through Project Properties, Run > VM Options, and Tools > Libraries on Windows 10 with NetBeans 25, JDK 17, and JavaFX 21. Compare direct JAR references with the Ant Library Manager setup and capture the runtime error. Done means establishing whether the behavior is a bug or expected configuration, then documenting or addressing the difference.

Written by the indexing model from the issue text.