How To Solve KM Problems Using the KM Debugger

That would be a good workaround, but every debugger I have ever used automatically presents a list of variables from those used in the code/script/macro. IMO, that is what we really need, and it must include Local and Instance variables.


I do not mind, but it needs to be improved.

Also why are we limited to just one "instance" of the value inspector, you might want one to be focussed on global variables and another just the macro in question.

1 Like

Thanks @DanThomas , I still have a lot to learn about Keyboard Maestro though I have been using it for years now at this point. An area in particular that I would really like to improve is understanding how to debug issues better. I feel like I waste so much time with trial an error and settle on things working when macros are not optimized and use pause actions more than I would like to.

If you have made video or know of any good videos on how to use the debug mode and showing it in use that would be great. I would love to watch a video series on Keyboard Maestro. Beginner, intermediate and advanced would be awesome! Someday someone will make them.

Your video that you made on inserting common saved macros has been awesome and something I have used thousands of times! I use it almost every time I make a macro in Keyboard Maestro and has been awesome. You have so many great posts on this forum of things you have shared. I would love to get to understand this better.

Most of the time I just use "prompt" commands, because it's quicker to narrow down the section that's causing problems. I'm sure there's better ways of doing it, but like most people, when I'm trying to solve a problem, I usually don't have time to learn new tricks. I still use these logging macros, but I use them mostly in macros that run based on a time of day - like kicking off backups. But knock on wood, that's been running so smoothly that I basically forget all about the logging. :smile:

1 Like

I have moved your post and related replies to this existing topic on KM debugging.

Debugging Resources

  1. Macro Debugger -- KM Wiki, June 2019
  2. KM 6 Macro Debugger Tutorial by Philippe Martin, May 2013
  3. Using the KM Debugger -- YouTube video by Ez Buttons, May 2014

Finally, I'll quote myself from above:

This is the main method I use for debugging KM Macros.
One other key point is to place a Debugger Breakpoint This Macro Action at places in my macro JUST BEFORE the Action where I suspect the bug is.


I change the color to red so I can easily identify and find it in my macro.
When I "think" I have resolved my issue, I just disable the Breakpoint Action, in case I need it later (which I often do).

The next time I have a real issue to debug, I will do a screen recording and post here.


1 Like

could you give an example of how you use prompts to debug ?
thank you

I'd love to see this as well. Sounds like you might just be using them as stopping points like Michael is doing with the Debugger Breakpoint. I typically use voice over to hear things said right before where I think issues might be. Hasn't felt the most efficient way to do it but it certainly has helped me find several issues. A recent macro issue I have had though that didn't help very much and things remained a mystery.

Glad to hear that.

Thanks, Michael, that would be great!

I read all those posts and rewatched that video (I had watched that several times when I first made the jump from QuicKeys years ago), I will have to play around more and see what I can learn. The more videos out there in this area the better for me. Especially something that shows debugging switching between applications and waiting for windows to pop up. Philippe talked about these but I would love to see this in action in a few videos.

Thanks for your help.

Debug techniques based on bitter experience (see 8 below)

1: Write perfect code.

Then you will never, never, ever need to debug.
Very, very, very few people on this planet have this ability.
Maybe you know one?
Maybe PeterNLewis is one?
I do not know, but I do know I am not one of them.

2: When you have sketched out your code, then think how you will test it, BEFORE you start writing it or testing it.

The analogy I would use is that you are playing a game of chess.
You have the White pieces.
The opponent is has the Black pieces.
You carefully analyse the position from the White perspective.

THEN, to test, you walk around to the other side of the board and look at the situation from the Black perspective.
i.e. you change your point of view and try and see how you will test this.

This will often throw up things you have not thought of because you are looking at it from a different point of view, typically unusual conditions, initialisation problems, race conditions, semaphore conditions etc.

3: Explain what you are trying to do to an imaginary dog, cat, or third person.
This makes you formulate the problem in a different way often leading to an “Ah-Ha” moment.
You do not need the dog or cat or whatever, it is just a question of changing your perspective on the problem. (I used to explain to my wife, but she used just carry on ironing, and ignore me completely, but it did the trick). If you are in an office, a fellow programmer or the office coffee machine is a suitable substitute.

4.Go for a walk round the block, do something else, and comeback to the problem later, sleep on it. Again it is a question of having a different perspective or a fresh look.

  1. Redefine the problem. If solution A is not working, then rewrite as a different solution
    e.g. assume you had to print the three times table from 1x3, 2x3 then the alternative solution would be print the 4 times table from 12x4 to 1x4 i.e. the same problem modified.

6a. Redefine the complete problem. Ie make it more generic e.g. tables 1…12 x 1…12
6b Redefine the complete problem. Ie make it more specific.

  1. Create test cases and scenarios and see what would happen

  2. Goto the pub and have a pint ( my personal favourite)


  1. Keyboard Maestro debug specifics.

9.1 Check you have not mis-spelt a variable name.

9.2 Add start and stop debug statements at key points

9.3 Change the name of Instance and Local variables to GLOBAL by adding say xx as a prefix.
e.g. Instance_loop_count_n becomes xxInstance_loop_count_n and therefore will appear in the Global variable list. Later, you remove the xx.

9.4 Create a debug macro that just consist of Display text in a window of ALL the variable names you are using. (This will not work for Local variables, so make all your variables either global or Instance unless it really really is a local variable) e.g. “Var123” >>> Its actual value so you know what is what. The advantage of the debug macro is that you can include at ANY point in the macro under test, but the variables must be global or Instances….

9.5 Do NOT do complicated functions in KM function calls
e.g. instead of say MOVETO( sqrt(var1 x var2) / var3)) do
temp_var = sqrt(var1 x var2) / var3)


then you can check on the value of temp_var

9.6 the KM debugger advances to “Nextstep”

You can “force” it to stop at intervening points by inserting dummy statements as

temp_debug_point is set to text “ I am now here”
code ~~~~~~~
temp_debug_point is set to text “ I am now here2 ”
code ~~~~~~
temp_debug_point is set to text “ I am now here3”

This stops the KM macro debugger running away and you know exactly where you are

This can be enhanced by

temp_debug_point is set to text “ I am now here3:: var 88 = %Variable%var88%

so you know the intermediate value.

9.7 XML. Save the macro by exporting to .kmmacro format i.e. XML.
Open the macro using an XML editor e.g. Atom.
This will enable you to search for specific strings especially if you have a variable name mis-spelt

9.8 Use KM> Prefs> variable and clipboard as these are updated in “realtime” as the macros is run.

9.9 It is remotely possible it is not your fault i.e. a bug in OSX, but in my experience this is rarely the case.

9.10.When all else fails ask JMichaelTx or one of the other major contributors to this forum.
I am going to rebadge myself as Caspian as Sleepy has been taken.

9.11 Here are some quotes from HitchHikers Guide to the Galaxy which are worth remembering, after all, it is only a “bug”.

9.11.a. “Funny,” he intoned funereally, “how just when you think life can’t possibly get any worse it suddenly does.”

9.11.b. The chances of finding out what’s really going on in the universe are so remote, the only thing to do is hang the sense of it and keep yourself occupied.

9.11.c. A common mistake that people make when trying to design something completely foolproof is to underestimate the ingenuity of complete fools.

9.11.d. Not unnaturally, many elevators imbued with intelligence and precognition became terribly frustrated with the mindless business of going up and down, up and down, experimented briefly with the notion of going sideways, as a sort of existential protest, demanded participation in the decision-making process and finally took to squatting in basements sulking.

1 Like

Most of the time I just add a prompt that says "Here", or "1". If the problem hasn't happened yet, then I add another prompt further on. The prompt might also display the values of some variables.

I learned a technique called "binary search" a million years ago, and it really helps track down where bugs occur. Put a prompt halfway through the code. If the prompt displays before the problem occurs, then add a prompt halfway between the prompt and the end - otherwise, add a prompt halfway between the prompt and the start. It doesn't take long to track it down.

Of course, there are some types of problems that prompts won't help, but hey, if it was easy, everyone would do it!


When you use the Debugger Breakpoint This Macro Action it opens the Debugger window, which shows the next Action, or branch in a IF/THEN or Switch, that will take place.

When I do debugging, I already have the Macro open in the KM Editor, and as I step through the debugger, I can scroll the Macro.

Here's another tip, which is good for both documenting your Macro and Debugging:
Change Action Names to Custom Name Describing the Specific Action

In the above screenshot, I had previously (when writing the Macro) changed the name of the IF/THEN to:
"IF: URL was FOUND; Open URL; ELSE Open Script"

1 Like

I have only just discovered the rename macro action option via the cogwheel and it can save an awful lot of comments

OK, guys, here is a very rough draft of a video demo of using the KM Debugger:

Demo Keyboard Maestro (KM) Debugger Case 1

It is about 17 min, and has NOT been polished in any way. I do plan on publishing a polished (probably re-recorded) version in the near future. But in the interest of sharing my debugging technique, I thought I'd share this very rough cut with you now.

If you start watching and are not getting any value out of it, then by all means feel free to quit watching.

I do invite constructive feedback, but please don't just say it's terrible. Please be specific, and if you can provide suggestions for improvement. If you would prefer, you can just reply with a "Helpful" or a "Not Helpful".

Please do ask questions, if you like. If what I show you does not make sense, then let me know and I'll try to clarify.

Thanks for your feedback.


That is a great tip I didn't realize that was there, thanks.

Thanks for making this video, great to see your workflow and how you the debugger macros in Keyboard Maestro. "Helpful"

As far as some hopefully constructive feedback, you know it is a rough video and I would take that in a heartbeat over no video to be sure. A few things that I know would take you more time and effort so take this with a grain of salt but only because you invited constructive feedback.

Smaller bit size chunks of each section of what you are doing. I made several video tutorials and found 2-5 minutes is about right. Make them in a small playlist of say "Keyboard Maestro Debugger Workflow"

Bite-Size Video 1: In the case of your video start with the Macro working and show us what it is supposed to do first. Then go back to the broken macro and run it and show where it fails.

Bite-Size Video 2: A simple explanation of each step of the macro and it's intended purpose. It doesn't need to go into the details of how the time format works and converts (that would be a different video in a different playlist). Just keep the focus on debugging macros.

Bite-Size Video 3: Using Keyboard Maestro debugging actions and seeing the errors in realtime and then fixing them.

Bite-Size Video 4: Explaining what the reason is for each debugger macro you added and support macros you are referencing (as in around 15 minutes).

Bite-Size Video 5: One or two other slightly more complicated video of debugging a macro using the stuff you already explained in the other video to get some examples of it in action.

Again all that being said that ups the ante quite a bit and keeps people from even making a video in the first place so seeing something in action and the processes used is very helpful. If I were to just boil it down to one quick video just show what the macro does working first and explain its purpose.

You have one new subscriber. Thank you for your time and for making this video!

1 Like

I apologize for the delay.
thanks very much for your video which I watched now a few times.
In it you refer to your error macro which seems very interesting, considering that I try to decipher my errors with the truncated 3 line notifications. Is your macro in the KBM library ?

I do have a version posted, but if you can wait a few days I have a major update that I'm testing, and will then upload.

1 Like

thanks. I will follow-up

@JMichaelTX how is that update going? I am certainly interested in checking it out.

I was just about to post my "KM Error Report" macro, and got notification of a change coming to KM soon that changes the error logging. So, I need to test and adapt my macro that those changes before I publish it.

Hopefully it will just be a few days.

1 Like

OK, @ronald et al: I have updated my macro with a major revision:

MACRO: Display Last KM Macro Error Ver 4 [Pub]

1 Like

very sorry. I had missed your message. Thanks very much !!