[Bug]: Mirror path inside `./iobroker-data` silently breaks script visibility — add UI warning and a safe default suggestion

[PackElend]

I'm sure that

• This issue is still present in the current beta version of this adapter
• There is no other (open) issue with the same topic (use the search!)
• This issue is not described in the adapter documentation / FAQ (read the docs!)

Script type

JavaScript

The problem

Dear iobroker team,
The following text was mainly generated by AI, but the issue is a real human experience.

I configured "Mirror scripts to file path" with the path /opt/iobroker/iobroker-data/scripts_mirror/. After enabling it, my script folder structure (global, common) and the scripts inside them disappeared from the Scripts tab.

I started to panic and search for solutions, as uninstalling and reinstalling the adapter did not resolve the issue either. This was particularly concerning as the folders were still listed when I added a script via the reinstalled adapter.

AI was kind enough to help me out by referring me to this little hidden gem: ioBroker.javascript/docs/en/upgrade-guide.md at master · ioBroker/ioBroker.javascript but even changing the path to /home/iobroker/script_mirror improved the situation.

I continued conversing with AI and figured out the script objects themselves were not lost — they still existed under script.js.* in the Objects tab (verified via export). But according to the AI:

• The ACL of the script.js.* objects had been set to 0644 (Everyone: read only, no write), which contributed to the scripts not displaying correctly.

After correcting the object ACLs from

back to read/write

and clearing the browser cache (a private window showed everything correctly), the scripts reappeared.

Root cause (as I understand it)

The chosen path is located directly inside ./iobroker-data, which is listed as a forbidden directory in
[docs/en/upgrade-guide.md](https://github.com/ioBroker/ioBroker.javascript/blob/master/docs/en/upgrade-guide.md)
("Forbidden directories for Script Filesystem Mirroring"). I only found this documentation later. From the user's perspective inside the Admin UI, there was no visible warning at the point where the path is entered, and the symptom
(scripts vanishing from the tab) gave no hint about the actual cause.

To Reproduce

1. Set "Mirror scripts to file path" to a subdirectory inside ./iobroker-data, e.g. /opt/iobroker/iobroker-data/scripts_mirror/
2. Save / restart the javascript instance
3. Open the Scripts tab → the script tree (global/common and scripts) is empty
4. Check Objects tab → the script.js.* objects still exist

Expected behavior

• The adapter should show a clear warning directly in the instance configuration UI, next to the mirror-path input field, when a forbidden path (per the upgrade guide) is entered — instead of only documenting it in the upgrade guide.
• Ideally the field could prefill / suggest a safe default path outside the ioBroker base directory, e.g. /home/iobroker/script_mirror, which matches the documented requirements (dedicated new directory, writable by the iobroker user, outside /opt/iobroker).
• Object ACLs should not be left in a state (0644) that hides the scripts from the Scripts tab.

Additional note

A short hint in the UI ("Path must be outside /opt/iobroker; a dedicated empty directory writable by the iobroker user is required") plus a sane default would likely prevent a whole class of "my scripts disappeared" reports.

how I can help
I can work on Script Engine, as it does not mention anything about the future of mirroring and its caveats.
To do so, I create an PR for updating ioBroker.javascript/docs/en/README.md at master · ioBroker/ioBroker.javascript?
Although it does not match Script Engine 100%.
This would improve the situation, as they would otherwise only find scattered information such as:

• Frage Javascript Update Script Filesystem Mirrorinng
• Scripteditor Unterschied zwischen common & global
• Javascript-Adapter Script-Mirror
• Script Mirroring - Einschränkung bei Pfaden seit v5.5.0
• Refactoring common/global Scripte · Issue #1779 · ioBroker/ioBroker.javascript

iobroker.current.log (in debug mode!)

No response

Version of nodejs

v22.23.0(22.23.1)

Version of ioBroker js-controller

7.2.2

Version of adapter

v9.3.1