Differences

This shows you the differences between two versions of the page.

--- Troubleshooting [2021/11/01 10:00] – peternlewis
+++ Troubleshooting [2025/10/03 09:53] (current) – peternlewis
@@ Line 1: / Line 1: @@
+~~INTOC~~
 ====== Troubleshooting ======
-This Wiki article is intended to address situations where you find that Keyboard Maestro does not work as you expect, or works in an unexpected way, and you have been unable to identify the cause and fix it.  This article aims to help you resolve this issue and make Keyboard Maestro work as you intend.   This article does _not_ address _how to_ questions (please post those to the [[https://forum.keyboardmaestro.com/|Keyboard Maestro Forum]]).
+This Wiki article is intended to address situations where you find that Keyboard Maestro does not work as you expect, or works in an unexpected way, and you have been unable to identify the cause and fix it.  This article aims to help you resolve this issue and make Keyboard Maestro work as you intend.   This article does _not_ address _how to_ questions (please post those to the [[/Forum|Keyboard Maestro Forum]]).
 ===== When Does the Issue First Occur =====
@@ Line 8: / Line 10: @@
 . Immediately after you have installed Keyboard Maestro on a specific Mac -- See [[#Situation_1_--_New_Install|Situation #1]].
-. Immediately after you have updated Keyboard Maestro to a new version -- See [[#Situation_2_--_After_Update_to_New_Version_of_Keyboard_Maestro|Situation #2]].
+. Immediately after you have update macOS -- See [[#Situation_2_--_System_Update|Situation #2]].
-. Keyboard Maestro’s behavior changes unexpectedly, and without apparent cause, some time (say a week or more) after it has been running as expected without any issues -- See [[#Situation_3_--_After_Working_Fine_for_a_While|Situation #3]].
+. Immediately after you have updated Keyboard Maestro to a new version -- See [[#Situation_3_--_After_Update_to_New_Version_of_Keyboard_Maestro|Situation #3]].
-. After you have created a new Macro, or added new Actions, that you have not used before -- See [[#Situation_4_--_After_New_Macros_or_Actions|Situation #4]].
+. Keyboard Maestro’s behavior changes unexpectedly, and without apparent cause, some time (say a week or more) after it has been running as expected without any issues -- See [[#Situation_4_--_After_Working_Fine_for_a_While|Situation #4]].
+. After you have created a new Macro, or added new Actions, that you have not used before -- See [[#Situation_5_--_After_New_Macros_or_Actions|Situation #5]].
 ===== General Troubleshooting =====
@@ Line 20: / Line 23: @@
 . **Restart Your Mac**
 . As with all unexpected behavior on your Mac, the first line of recovery is to restart your Mac.
-. Often it will be a permanent fix, but sometimes the issue will reoccur after some time
+. Often it will be a permanent fix, but sometimes the issue will reoccur after some time.
 . Try this first, and then you only need to do more troubleshooting if the issue returns.
 . **Run the [[Troubleshooting#Use_the_Interactive_Help_Wizard|Interactive Help Wizard]] from the Keyboard Maestro Editor Help menu**
-. Choose the “Something expected is not happening” or “Something unexpected is happening”
+. Choose the “Something expected is not happening” or “Something unexpected is happening”.
-. Keyboard Maestro will check all of the key requirements and display the results, like this:
+. Keyboard Maestro will check all of the key requirements and display the results.
- {{ :wizard-expected-status-results.png?nolink |}}
 . See [[Troubleshooting#Run-Away_Login_Macros|Options for Launching Keyboard Maestro Editor]]
-. **More Help From Apple**\\
-[If an app freezes or quits unexpectedly on Mac - Apple Support](https://support.apple.com/guide/mac-help/if-an-app-freezes-or-quits-unexpectedly-mchlp2579/10.14/mac/10.14)
 ==== Situation #1 -- New Install ====
@@ Line 45: / Line 45: @@
 . To fix, see [How to Enable Google Chrome to Respond to KM Actions](https://forum.keyboardmaestro.com/t/announcement-google-chrome-68-disables-km-access-how-to-fix/10969)
-==== Situation #2 -- After Update to New Version of Keyboard Maestro ====
+==== Situation #2 -- After a System Update ====
+If Keyboard Maestro had been running fine, and then does not work as expected after upgrading macOS:
+. Immediately after a system update, it is wise to Restart an additional time. Many times we have found the system to not be in a totally stable state after an update, and a Restart gives a clean fresh start.
+. If lots of macros are failing, run the _Interactive Help Wizard_ from the Keyboard Maestro Editor Help menu and see if that helps.
+. Check the Security preferences pane and verify that you have all the relevant security permissions.
+. Keep in mind that after a system update (or any specific application update), your macro might break simply because things in the system or application have changed since the macro was created. See if the macro simply needs adjusting.
+==== Situation #3 -- After Update to New Version of Keyboard Maestro ====
 If Keyboard Maestro had been running fine, and then does not work as expected after an upgrade, then do the following:
@@ Line 51: / Line 60: @@
 . As usual, restart your Mac.  This will likely fix the issue.
 . Run the _Interactive Help Wizard_ from the Keyboard Maestro Editor Help menu.
-. If the issue persists, then you _may_ have found a bug.  To confirm and get feedback for possible workarounds, post your issue in the [Keyboard Maestro Forum](https://forum.keyboardmaestro.com/).  Be sure to provide:
+. If the issue persists, then you _may_ have found a bug.  To confirm and get feedback for possible workarounds, post your issue in the [[/Forum|Keyboard Maestro Forum]].  Be sure to provide:
-. Your versions of macOS and Keyboard Maestro
+. Your versions of macOS and Keyboard Maestro.
-. Observed Behavior
+. Observed Behavior.
-. Expected Behavior
+. Expected Behavior.
 . Upload example Macro that produces the issue.
-==== Situation #3 -- After Working Fine for a While ====
+==== Situation #4 -- After Working Fine for a While ====
 . If Keyboard Maestro has been working well, as expected, for a while (let's say a week or more), and then it suddenly behaves in an unexpected manner, then most likely that is due to something that has recently changed.\\
 So, ask yourself what has changed:
-. Keyboard Maestro update
+. Keyboard Maestro update.
-. macOS updates
+. macOS updates.
-. Install of new apps, or app updates
+. Install of new apps, or app updates.
-. Especially any utilities (like Clipboard managers)
+. Especially any utilities (like Clipboard managers).
-. etc
+. etc.
-. If you identify a recent change, then you need to determine if that is causing the issue with Keyboard Maestro\\
+. If you identify a recent change, then you need to determine if that is causing the issue with Keyboard Maestro. The best way to do this is to [Start up your Mac in safe mode](https://support.apple.com/guide/mac-help/start-up-your-mac-in-safe-mode-mh21245/mac).
-The best way to do this is to [Start up your Mac in safe mode](https://support.apple.com/guide/mac-help/start-up-your-mac-in-safe-mode-mh21245/mac).
 . This will prevent all start-up items from starting.
 . Then launch KM and test your macros.
@@ Line 74: / Line 82: @@
 . If that does not help, then you can search (using the Browser Find menu) the below Keyboard Maestro specific issues to find one or more that relates to your situation.
-==== Situation #4 -- After New Macros or Actions ====
+==== Situation #5 -- If a Macro “Does Nothing” ====
+. The issue is most likely caused by improper macro activation.
+. Use the Interactive Help in the Help menu to determine if the macro is active.
+. It will also show you if the macro triggers.
+. If it triggers, it might be a problem with your actions, see the next section.
+==== Situation #6 -- After New Macros or Actions ====
 . The issue is most likely caused by improper use of the Action.
 . Click on the _Gear_ popup menu at the top right of the Action, and select _Help_ to get detailed help from the Wiki.
-. If the previous Action was a command to an app, then you may need a short _Pause_ after that Action.
+. If the previous Action was a command to an app, changed the window or focus, then you may need a short _Pause_ after that Action.
-. If you still can't resolve the issue, then submit a topic to the [Keyboard Maestro Forum](https://forum.keyboardmaestro.com/).  Please read [Tip: How Do I Get The Best Answer in the Shortest Time?](https://forum.keyboardmaestro.com/t/tip-how-do-i-get-the-best-answer-in-the-shortest-time/10797)
+. If the action might be failing, first ensure the the Keyboard Maestro Engine can display notification (otherwise it might be telling you the action is failing and you are not seeing it).
+. You can also check for any errors reported in the Log file. Choose Open Logs Folder from the Help menu and you can see anything reported in the Engine.log file that might indicate a problem - this will also confirm that the macro is triggering - if not, check out the previous section for answers related to that.
+. If you still can't resolve the issue, then submit a topic to the [[/Forum|Keyboard Maestro Forum]].  Please read [Tip: How Do I Get The Best Answer in the Shortest Time?](https://forum.keyboardmaestro.com/t/tip-how-do-i-get-the-best-answer-in-the-shortest-time/10797)
 ===== Use the Interactive Help Wizard =====
@@ Line 85: / Line 102: @@
 Generally Keyboard Maestro will only do what you tell it to do, but sometimes that can still result in something you don’t expect happening.  Here is what to do:  (v8+)
-* Choose Interactive Help (previously Assistance) from the Keyboard Maestro Editor Help menu.
+* Choose Interactive Help from the Keyboard Maestro Editor Help menu.
-{{:wizard-initial-display.png?nolink|}}
 * Then choose one of the following:
@@ Line 93: / Line 108: @@
   * Something expected is _not_ happening...
-==== Something Expected is Not Happening ====
+Then follow the instructions.
-* Click the *Something Expected is _not_ happening* link.
-{{:wizard-expected-step-1.png?nolink|}}
-Click _Continue_
-{{:wizard-expected-step-2.png?nolink|}}
-Click _Continue_
-{{:wizard-expected-step-3.png?nolink|}}
-Click _Continue_
-{{:wizard-expected-step-4.png?nolink|}}
-==== Something Unexpected is Happening ====
-* Click the *Something unexpected is happening* link.
-{{:wizard-unexpected-med.png?nolink|}}
-* Click the *Quit the Engine* link.
-* If the issue remains, the problem is almost certainly unrelated to Keyboard Maestro.
-* Click the *Launch the Engine* link to relaunch the Keyboard Maestro Engine.
-* If the issue returns, check the recently executed macros which are listed in the window.
-{{:wizard-unexpected-step-2.png?nolink|}}
-* If the issue remains and there are no macros being triggered, ask Support for help.
 ===== Macro Issues =====
 ==== Macros Not Firing (Triggered) ====
 A relatively common situation occurs when a macro you expect to fire is not firing.  Here is what to do:  (v8+)
@@ Line 157: / Line 137: @@
 * If the macro triggers, but does not do what you expect, then you need to look at the actions.
-==== Macros Not Firing After I Login ====
+==== Macros Not Firing After You Login ====
-The macros are all enabled by the Keyboard Maestro Engine.  You can start it by launching the Keyboard Maestro application, or have the engine start automatically by enabling the “Launch Engine at Login” preference in the Keyboard Maestro General Preferences pane.
+The macros are all performed by the Keyboard Maestro Engine.  You can start it by launching the Keyboard Maestro application, or have the engine start automatically by enabling the “Launch Engine at Login” preference in the Keyboard Maestro General Preferences pane.
 ==== Run-Away Login Macros ====
@@ Line 169: / Line 149: @@
   - **Launch the Keyboard Maestro editor app without starting its _Engine_**
-    - Hold down <kbd>⌘</kbd><kbd>⌃</kbd><kbd>⌥</kbd><kbd>⇧</kbd> (that's Cmd-Control-Option-Shift) and click on the _Keyboard Maestro app in the Dock_, or double-click in the _Applications_ folder.
+    - Hold down <kbd>⌘</kbd><kbd>⌃</kbd><kbd>⌥</kbd><kbd>⇧</kbd> (that is Command-Control-Option-Shift) and click on the _Keyboard Maestro app in the Dock_, or double-click in the _Applications_ folder.
     - This will quit the Keyboard Maestro _Engine_ and start the Keyboard Maestro app _without_ starting its _Engine_.
-    - Locate the problem Macro, and remove the trigger or disable it\\
+    - Locate the problem Macro, and remove the trigger or disable it.
   - **Restart Your Mac in [[https://support.apple.com/en-us/HT201262|Safe Mode]] Without Login Items**
     - Use this option if //none of the above work//.
-    - Hold down <kbd>⇧</kbd> (that's Shift) immediately after you select //Restart..//. from the Apple menu.
+    - Hold down <kbd>⇧</kbd> (that is Shift) immediately after you select //Restart..//. from the Apple menu.
     - This will prevent the apps/processes in your //System Preferences > Users & Groups > Login Items// from launching (opening) when you log in, including the Keyboard Maestro Engine.
     - Then Hold down <kbd>⌘</kbd><kbd>⌃</kbd><kbd>⌥</kbd><kbd>⇧</kbd> when you launch Keyboard Maestro.
@@ Line 186: / Line 166: @@
 ==== Timing Between Actions ====
-Here's a common situation: You've written your macro, you're sure you've included all the steps, but the macro fails in some way, e.g. it seems to skip steps. This is often caused by timing issues: Keyboard Maestro executes an action in the macro before the receiving program is ready for that action.
+A common situation is that you have written your macro, you are sure you have included all the steps, but the macro fails part way, e.g. it seems to skip steps or stops half way. This is often caused by timing issues: Keyboard Maestro executes an action in the macro before the receiving program is ready for that action.
 Most of the actions in a script are immediate: Keyboard Maestro will execute them and then attempts to wait until they are completed, but for some actions it is not possible to tell when the action is completed.  So Keyboard Maestro will move on to the next step immediately. If Keyboard Maestro does not wait sufficiently long for the result of an action, you must tell it to explicitly.
@@ Line 192: / Line 172: @@
 To make the macro wait, there are two options:
-* Pause: this adds a pause of a fixed length
+* [[action:Pause|Pause]]: this adds a pause of a fixed length
-* Pause Until: this tells Keyboard Maestro to wait until something happens (e.g. a new window opens, a key is pressed, and a dozen more options).
+* [[action:Pause_Until|Pause Until]]: this tells Keyboard Maestro to wait until some [[/Conditions|condition]] is met (e.g. the front window title, a key is down, and a dozen more options).
+* [[action:Pause_Until_Change|Pause Until Change]]: this tells Keyboard Maestro to wait until something happens (e.g. the clipboard or front application changes).
-Often, adding pauses to your macro will solve the timing issues. A pause of 0.3 seconds is often enough, but in some cases (e.g. a 'Switch to application' action when there are many applications open and your system is running out of memory) longer pauses (several seconds) may be necessary.
+Often, adding pauses to your macro will solve the timing issues. A pause of 0.3 seconds is often enough, but in some cases (e.g. a [[action:Activate_a_Specific_Application|Activate a Specific Application]] action when there are many applications open and your system is running out of memory) longer pauses (several seconds) may be necessary.
-===== Action Issues =====
+===== Typing Issues =====
 ==== Sometimes Typing in Password Fields Drops Characters ====
@@ Line 207: / Line 188: @@
 This happens most commonly when you have a hot key trigger with the same key (eg Control-T) as a key you want to type in to a password field (eg "Hello there").  Because it is a password field, the only indication will be a missing bullet (•) (so ten instead of 11 bullets) and then an "invalid password" error, which makes this problem hard do diagnose.
+==== Sometimes Typing results in Characters Missing or out of Order ====
+This typically happens in web fields (especially Facebook) or cross platform apps.
+The system has a queue for keyboard events, so they are sent by Keyboard Maestro in the correct order and then processed by the system  in that order. The problems happen after that.
+Typically you see this in fields where the app is processing the field. Essentially the app reads the field, does some processing or checking and then writes the field back, and the typing happens fast enough (as could keyboard typing if you could type fast enough) that changes happen while the field is being read/written and so characters are jumbled or lost.
+You can slow the typing down by using Set Action Delay action (https://wiki.keyboardmaestro.com/action/Set_Action_Delay) to increase the delay for normal typing. Only do it for the current macro (not permanently) since this issue is relatively rare, and generally only applies to certain apps or fields.
+==== Everything is lowercase in remote desktops/virtual machines ====
+Yes, unfortunately these types of environments seem to miss the shift key and the consequential uppercasing of lettings and symbols.
 ===== Clipboard Issues =====
@@ Line 284: / Line 277: @@
 Eg:
+    * Set Clipboard to Styled Text %CurrentClipboard%
+    * Filter Clipboard: Remove Styles
-    Set Clipboard to Styled Text %CurrentClipboard%
+===== Keyboard Maestro Issues =====
-    Filter Clipboard: Remove Styles
+==== Accessibility ====
+Keyboard Maestro requires accessibility permissions to perform many of its actions. Sadly the macOS system security permissions have been quite buggy since Mojave, and continuing through at least Monterey. See the [[assistance:Accessibility_Permission_Problem|Accessibility Permission Problem]] assistance for more information if you have trouble setting hot keys, typing keys, moving windows, etc.
-===== Keyboard Maestro App Issues =====
-==== App Freezes (Locks up, Spinning Beachball) or Other Strange Behavior due to SIMBL ====
-If Keyboard Maestro freezes, locks-up or is exhibiting very strange behavior, check to see if you have [[https://en.wikipedia.org/wiki/SIMBL|SIMBL]] installed in this folder:
-`/Library/Application Support/SIMBL/`
-**SIMBL** is very clever, but some of its extensions can lead to bizarre behavior, crashes, freezes and other strange, unexpected behavior in one or more apps or the macOS itself.  So if you have it installed, pretty much all bets are off as far as stability goes for your Mac.  See [[https://macremover.com/uninstallguides/2018/06/19/remove-mysimbl-macos/|How to remove mySIMBL and SIMBL in macOS]].
-**More Help From Apple:**\\
-[If an app freezes or quits unexpectedly on Mac - Apple Support](https://support.apple.com/guide/mac-help/if-an-app-freezes-or-quits-unexpectedly-mchlp2579/10.14/mac/10.14)
 ==== Secure Input Mode ====
@@ Line 309: / Line 292: @@
 Keyboard Maestro 6 and later detects the case where the Secure Input Mode flag is left on and alerts you to the issue.
-Choose Interactive Help (v9+) (previously Assistance in v8) from the Help menu and click the *Something unexpected is happening* link and Keyboard Maestro will tell you if there are any obvious issues.
+Choose Interactive Help (v9+) from the Help menu and click the *Something unexpected is happening* link and Keyboard Maestro will tell you if there are any obvious issues.
 A related, very unusual case is that Terminal has a Secure Keyboard Entry mode (in the Terminal menu) - if you turn that on, that may also cause problems.
@@ Line 363: / Line 346: @@
 assuming that `Keyboard Maestro.app` is in the Applications folder.
 ===== Palette Issues =====
@@ Line 377: / Line 358: @@
 If you wish to briefly hide all the palettes (eg while watching a video), you can use the [Conceal Macro Palettes until Application Switch](https://wiki.keyboardmaestro.com/action/Conceal_Macro_Palettes) action.
-==== White Menus or White Switchers or Palettes ====
-For some people, the menus or switchers sometimes appear completely white.  When this happens, restarting Keyboard Maestro Engine is the only solution.
-It is also seen in Photoshop and maybe other applications.  See [this thread](http://feedback.photoshop.com/photoshop_family/topics/photoshop_menus_become_completely_blank) or [this thread](http://forums.adobe.com/thread/1320946)
-According to those threads, Adobe believe the issue to be a Mac OS X bug, and have a patch solution to resolve it (within Photoshop) and are working with Apple to resolve the problem properly.
-This issue appears to have been resolved in 10.9.3 and later.
@@ Line 408: / Line 379: @@
 ===== Script Issues =====
-==== Execute Script Actions are Not Working ====
-Your variables are sent to your scripts by placing them in environment variables. However, the total size of the environment variables is 256k.  Therefore if the total size of your variables exceeds about 256k scripts will stop working.  Adjust your variables to reduce the total size.
@@ Line 420: / Line 386: @@
 To learn how to set a path in a Keyboard Maestro Execute Shell Script Action, see
-[[action:Execute_a_Shell_Script#Path_in_Shell_Scripts|Execute a Shell Script]]
+[[action:Execute_a_Shell_Script#Path_in_Shell_Scripts|Execute a Shell Script]].
@@ Line 492: / Line 458: @@
 ===== macOS Issues =====
-==== Yosemite and Accessibility Settings Problems ====
-Yosemite (10.10 GM1 through 10.10.2) has a serious problem adding applications to the accessibility pane properly.  This is affecting other applications that require accessibility as well.  It seems to commonly impact Keyboard Maestro by the Keyboard Maestro Engine not being added to the accessibility settings pane.
+==== Mojave and Later Security Preferences Issues ====
-This bug was finally resolved in Yosemite 10.10.3.  So if you are having problems with accessibility under Yosemite, upgrade to 10.10.3 or later, and then launch Keyboard Maestro.  Then ensure both Keyboard Maestro and Keyboard Maestro Engine are listed and checked.
+Sadly the System Security Permissions have been rather buggy since Mojave, and this continues right through to Monterey. Combined with the increasing number of different permissions you need to enable can make it challenging when starting out with Keyboard Maestro, or after major system updates. These forum topics cover various issues:
-If you must stay on version 10.10.0-2 for any reason, see the forum topic on [possible solutions](http://forum.keyboardmaestro.com/t/yosemite-accessibility-permission-problems/541/18).
-==== Mojave and Catalina Issues ====
 See Forum topics:
   - [Resolving Catalina/Mojave Accessibility/Security Permissions Issues ](https://forum.keyboardmaestro.com/t/tip-resolving-catalina-mojave-accessibility-security-permissions-issues/16620)
-==== Big Sur Issues ====
-See Forum topics
   - [Resolving Big Sur Accessibility, Security, and Other Issues ](https://forum.keyboardmaestro.com/t/tip-resolving-big-sur-accessibility-security-and-other-issues/20159)
   - [macOS Big Sur: Using and Upgrading To ](https://forum.keyboardmaestro.com/t/macos-big-sur-using-and-upgrading-to/19637)
 ===== Virtual Machine Issues =====
@@ Line 518: / Line 473: @@
 In Parallels, make sure the ”Enabled Mac OS X system shortcuts” preference is enabled, which will ensure Parallels reads the keyboard from the keyboard queue.
 ===== Other Issues =====