I have seen sporadic issues with PS throwing errors when calling await require(‘my-uxp-hybrid.uxpaddon’). The error thrown in the UXP JS dev console is “Failed to load Addon”.
I have encountered a machine which fails 100% of the time - which is at least very convenient for testing. Aside from that one machine that fails consistently, I have generally seen others fail but infrequently (ie there are several machines where it works most of the time and then on rare occasions fails).
The failure is always at the first require(). It either loads and works, or fails immediately. This suggests some kind of problem external to the UXP JS / hybrid C++ plugin. I tested with all other UXP plugins disabled to rule out any potential interaction, still fails. I assume that the root issue involves either the operating context or a back end race condition in PS when initializing the plugin.
The C++ source code is rather simple. The C++ plugin is code signed (signtool.exe confirms the file is signed). The UXP manifest is setup correctly.
Using icacls in the command prompt reports either full control [(I)(RX)] or at least execution privileges [(I)(RX)] for the uxpaddon file itself. No malware warnings or anything other than Windows Defender on this system.
I am unclear what additional steps I could take to help debug the nature of why PS is throwing “Failed to load Addon”.
@pkrishna@jsbache@justin2taylor@Jarda@DavideBarranca Any thoughts on a possible way to debug what is causing hybrid plugin failures? It should be easy to test now that I have a reliable failure case. Is there a way to get more specific debugging info from PS when it throws this error?
Details of machine that fails at require 100% of the time:
PS v26.1.0 20241113.r.121 158e617 x64, running Dutch local language
Windows 11 64 bits
The effort is split between UXP core and Photoshop.
Stage 1 is Photoshop verifying that the plugin is in a correct location and that the plugin is using apiVersion 2. If any of these checks fail, then you will see one of these messages in the console (logged as error):
“addOns requires apiVersion 2”
“The file system location of the plugin does not allow for loading of addOns”
For security reasons, Photoshop only allows for loading a plugin from devtools or from a market place install.
Stage 2 is Photoshop loading the actual module. If this fails we provide a load error message back to UXP, and I assume that UXP reject the load request with the error message that we return.
Hi @jsbache, thank you for the suggestions here. I’ll do some digging, but I am not sure that explains the issue here.
Neither front-end consideration is an issue (and I wouldn’t have success on any Windows system if I failed these).
The security question definitely catches my attention, as the failure here is in the context of beta testing with customers - so they do not have UDT, have not enabled Prefs / Plugins / Enable Developer Mode, and are not installing from the marketplace (in this context, that is how I will distribute in the end). However, I have tested this with several MacOS users with zero issues and have at least one Windows computer which is succeeding. So if the intention is for C++ hybrids to be disabled for standalone CCX installation, it is not working consistently.
I’ll try enabling dev scenarios on the failed machines to see if that allows things to work. Can you confirm if the supported environment is “enable developer mode”, UDT, or both?
Separately, I think it would be very helpful if the “failed to load addon” message could be reviewed and made more specific. If it is failing for security validation reasons, it would be very helpful to be warned of that - which would rule out concerns with the code, code signing, PS, or the host OS. It’s pretty difficult to debug without more clear feedback.
I should add that I hope direct CCX installation is not disabled.
Ultimately, users should have the freedom to make their own decision on plugins. The Adobe installer is already providing an elevated notice when someone installs with a C++ binary, and the OS should at least be checking for code signing and the normal defensive mechanisms users would encounter with most software.
Direct CCX installation is necessary for many cases where the Adobe marketplace is not the ideal mechanism for distribution (there are many important reasons here), for beta testing, and for supporting institutional licenses not supported by the marketplace.
But for the purposes of this troubleshooting, I do want to at least understand if it is the reason for failure. I just tried turning off developer mode and the plugin still runs fine on MacOS and Windows. But have not yet confirmed if enabling it helps on the computers which previously failed.
It’s tricky to debug such plugins remotely as they aren’t standalone executables. Is there any way to get PS to pass on any additional detail on the nature of the failure trying to load a hybrid plugin (some missing external dependency, exit code, security block, code signing issue, etc)?
First step is to take a look at the UXP log files. UXP/Photoshop messages may be captured there.
Location on macOS:
/Users//Library/Logs/Adobe/Adobe Photoshop 2025/UXPLogs_xyz.log
@jsbache I have reviewed the logs from the computer which failed. I’m not sure exactly what I’m looking for, but tried searching the following: Plugin {manifestID}, [Error], failed, and uxpaddon. Any other text you recommend searching for?
I see these errors:
[Error] [general] Plugin 0a4bb5cd_beta : Addon Load failed with error : The specified module could not be found.
[Info] [general] Addon Terminate Failed for Plugin with Id:TEST, addon will be unloaded.
How would you interpret these errors? The “could not be found” error message is a bit strange. I believe my plugin is properly codesigned and we haven’t seen anything marked for anti-virus detection (ie false positive), but I’m not sure how to definitely rule out either. Is there a Windows CLI command you know which would clearly rule out the risk that the plugin was simply quarantined by Windows or AV? Tricky for me as it isn’t a standalone executable I can run outside of PS.
I also see a couple of lines missing detail that say:
[general] Uncaught JS Exception:
However, I don’t see any reason to think those are driven by the UXP test plugin.
I believe that “The specified module could not be found” is a win32 error.
ERROR_MOD_NOT_FOUND 126 (0x7E)
The specified module could not be found.
This means that it is the LoadLibraryW call that fails.
One case for this can be that you are distributing a debug version of the dll and the user does not have the required runtimes. If you are distributing a release version you still need to make sure that you also distribute matching runtime libraries:
@jsbache I think you hit the nail on the head. Looks like I probably shot myself in the foot here. I’ll build in some guardrails to catch automatically. Thank you so much for the help to understand the scenario, very much appreciated!