Plugins - How to raise error back to KM?

Let’s say I’m writing a plugin, and I want to report some catastrophic error. What do I do so that KM will fail the plugin action with my error message?

I’d like to know how to do this for a JXA script that is run via a Shell script, like this:

osascript -l JavaScript <<JXA_END 2>/dev/null
(function (value) {
    'use strict';

    if (!value)
        throw Error("Value is required");


but I’d also like to know with AppleScript also (the AS would not be run through bash, of course).

Hey Dan,

Are you running from Bash for a specific reason (instead of using an Execute a JavaScript For Automation action)?

If so – out of curiosity – what is it?

I’m not aware of any method of hooking into Keyboard Maestro’s own error reporting mechanism.

You have to return your own error values and build your own reporting routine.

I need to create one generic error-reporting macro to call in such instances, but I haven’t bothered so far.


PlugIns, like pretty much all the Execution actions return strings. There is currently no ability to return a failure that Keyboard Maestro can recognize.

Yes - it’s because it’s a plugin. I don’t believe there’s any other way to use JXA in a plugin.

The fact that it’s a plugin is the entire issue. With a plugin, I don’t have the option of writing code that does things after the script has been run.

For non-plugins, unless the JXA is extremely simple, I have a design pattern for returning errors. The JXA script returns results by setting KM variables. The success/failure status is returned through the string "return"ed from the JXA function. If “OK” is returned, then no errors. Anything else is considered an error.

(But I have to keep reminding myself to take into account the possibility of having “warning: failed to get scripting definition from /usr/bin/osascript” in the result. I may have to rethink the pattern some - perhaps return the success/fail state in a variable also, using try/catch).)

But with plugins, I can’t do this, because I can’t really return results in variables then run KM code after the JXA to do something with the variables.

Thanks. So I can’t even validate the plugin’s parameters and fail if there’s an issue, right?

I have no idea how you would do it, but it would be nice if there was some way to “raise” an error from the plugin back to KM.

This is the problem. The return result is a string. The only option would be some sort of code that you could send out of a script/plugin that would indicate a failure. Pretty ugly.

Now that I think about it, you’ve already got a way to handle this. stderr.

With a regular “Execute a JavaScript” action, there’s an option for whether to “Include Errors” or not. “Errors” includes text from a thrown exception. And I assume “errors” means output to stderr.

So how about you give Plugins an optional plist parameter that says that if there’s anything in stderr, it’s an error message, and the error should be displayed and the macro canceled?

Or whatever makes sense to fit in with the rest of KM Actions.

How about that?

The next version will allow Notify/Failure on error in Execute script actions, and will return the error in %ActionResult%. Failure is based on the termination status of the script.