For more information about a specific Keyboard Maestro feature consult the Keyboard Maestro Documentation, post a question to the Keyboard Maestro Forum, visit the Keyboard Maestro web site or this wiki or contact_us.
We always respond to email, however email is no longer a guaranteed medium and spam filters can delete your message to us or our message to you. Messages sent using the feedback form will always get to us, emails sent to us will pretty much always get to us, but if you do not receive a response within a couple business days check your spam filters to see if they have trapped our reply. If you use the feedback form and want a reply, make sure you enter your email address!
Another common situation, a macro you expect to fire is not firing. Here is what to do:
Basically, you have to discover if the macro is active, if the trigger is firing, or if the actions are failing.
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.
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.
Start by quitting the Engine (File ➤ Quit Engine). If the issue persists, it might not be Keyboard Maestro. If not, relaunch the Engine (File ➤ Launch Engine) and verify the issue returns. Then check for recently executed macros by clicking on the [⌘] button at the top of the Keyboard Maestro editor window which lists them.
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.
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.
To make the macro wait, there are two options:
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.
If Typed String triggers are not working, or if you try to create a hot key and find that when you select the hot key it turns blue, but then when you type a keystroke it is not noticed, then there are two possible causes.
If Access for Assistive Devices is not enabled, then Keyboard Maestro cannot watch the keyboard for keystrokes. Keyboard Maestro warns you of this when you launch it, as well as with a small yellow warning triangle in the bottom right corner of the main window. Click on the triangle and follow the instructions to enable access for assistive devices. In Mavericks, the accessibility preferences are in the System Preferences Security & Privacy panel, Privacy pane - there are some reports that Mavericks can get confused if you have two different versions of Keyboard Maestro on your Mac, so check that panel closely.
An alternative cause for this issue is Secure Input Mode.
Mac OS X will not let applications watch the keyboard when you are in a password field (to prevent hackers getting hold of your passwords). However, the system can sometimes get into a state where it thinks it is permanently in a password fields. The most common cause of this is some versions of the 1Password/Chrome extension and the LastPass/Chrome extension, but almost anything that asks for a password could cause the problem (eg, VPN connections, Mail, etc). Quitting Chrome (or the appropriate affected application) or restarting will resolve the issue (until it reappears). Keyboard Maestro 6 detects the case where the Secure Input Mode flag is left on and alerts you to the issue.
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.
And a final new cause for this may be Parallels Version 8, which apparently can interfere with the keyboard event queue and/or hot keys. Restarting Parallels may help.
There is a forum topic on the subject and the Smile Software folks have a good page on this subject as it affects TextExpander similarly to Keyboard Maestro.
Note that there is nothing Keyboard Maestro can do to “work around” Secure Input Mode - it is a system security feature that has been erroneously left on. Keyboard Maestro can detect and report it, but it can no more work around the problem that it could bipass any other security features of Mac OS X.
As of 7.1+, Keyboard Maestro will tell you if it detects the system is in Secure Input Mode and if possible indicate the process which is causing the issue in the Keyboard Maestro status menu or by clicking the yellow warning triangle in the bottom right corner of the Keyboard Maestro editor. For older versions, there is a macro to find the offending app on the forum.
If your macros are not being saved (ie, you make changes in Keyboard Maestro, and then quit and relaunch Keyboard Maestro and the changes are lost, and Keyboard Maestro Engine never notices any changes) then this is likely because Keyboard Maestro cannot save the macros file. In Keyboard Maestro, choose Help → Open Preferences Folder, and ensure that that folder is writeable and that the Keyboard Maestro Macros.plist file it contains is writeable. If you're still having the problem, consider using the Disk Utility’s Fix Permissions action, and/or removing the Keyboard Maestro preferences folder, creating a new once, and moving the contents of the old one to the new one.
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.
When I hide Mail, and then show it later, the insertion cursor has disappeared, what’s up with that?
Congratulations, you have found a bug, but it is a bug in Mac OS X and/or Mail. You can reproduce this vanishing insertion cursor without Keyboard Maestro by quitting Keyboard Maestro and the Keyboard Maestro Engine, switch to Mail, create a new Mail message, with the insertion point blinking away. Command-Tab to the Finder, then Command-Tab, select Mail, press H to hide it, select the Finder. Then Command-Tab, select Mail. You can now type, but there is no insertion point. Switching the front two windows twice restores the cursor.
But, aha! You have Keyboard Maestro! Why do something manually when you can automate the process. Make a macro that is triggered when you activate Mail, with actions:
Problem solved until Apple get around to fixing the issue. This bug in Mail appears to be resolved in Yosemite.
In essence, the default path in a Keyboard Maestro Execute Shell Script is nothing, since Keyboard Maestro executes scripts using the bash shell in non-interactive mode.
To learn how to set a path in a Keyboard Maestro Execute Shell Script Action, see
Execute a Shell Script
Occasionally, you can have cases where you try to Insert Text by Pasting, or Paste from a Named Clipboard or the like, and the wrong thing is pasted.
There are two potential causes of this. The first is that some applications may cache the clipboard, resulting in the new clipboard that Keyboard Maestro sets not being seen by the application. This is particularly prevalent in cross platform applications or applications that expect very large clipboards. A solution to this may require setting the clipboard, and then executing some other action to wake up the application to the change, such as changing out of the application and then back, or clicking in the menu bar.
A more common, but more random, cause is due to the different nature of setting/reading the clipboard, and simulating a Command-C/Command-V to copy/paste. To understand what is going on, keep in mind:
Keyboard Maestro includes an automatic delay after posting a command key to allow the application to process it, but it's possible for the system / application to be slow in processing it and thus resulting in the wrong order of execution. For example, if you do this:
Insert Text by Pasting "A" Insert Text by Pasting "B"
The sequence is actually:
Set Clipboard to "A" Post a Command V to the keyboard event queue Pause a short while Set Clipboard to "B" Post a Command V to the keyboard event queue Pause a short while
If the application / system is slow, then the pause will not be long enough, and what will actually happen on the application end is:
The clipboard changes to "A" The clipboard changes to "B" A Command-V is received A Command-V is received
So B will be posted twice. A similar affect can happen if you actively delete the pasted clipboard using the Delete Clipboard action - the old clipboard may be restored before the Command-V is processed.
There are four possible solutions to ensure robustness in these sorts of cases:
When Keyboard Maestro simulates a keystroke, it simulates both the press and the release. If the key is already being held down by you (eg because you pressed the key as a trigger), then Keyboard Maestro notices this, and first releases the key, and then presses and releases the key.
However, in a password field (or any time Secure Input is enabled), Keyboard Maestro and other applications cannot see the state of the keyboard (for obvious security reasons). Because of this, Keyboard Maestro does not know that you are still holding down a key and therefore cannot know to release it. So if it tries to simulate the same key that you are holding down, in a password field, it will still simulate the press and release, but because the key is already held down, the press will not do anything and the keystroke will be lost.
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.
Although most people consider the clipboard to be a single thing (an image, some styled text, an slide in Keynote, whatever), in truth a single clipboard entry is made up of a variety of different things, each somehow representing the thing you copied.
For example, if you copy some text in Pages, then the clipboard might contain a variety of things like:
These different forms of the information on the clipboard are called “flavors”.
When an application pastes anything from the clipboard, it tries to choose the best representation. So Pages or Numbers might use the iWork representation of the text, another word processor might use the RTF version, a plain text application like BBEdit might use the UTF8 text, an image application like Acorn might use the image, and so on.
Generally, these different pieces of information should all be logically the same. That is, you would expect that if you paste in the RTF, and then remove styles, you would get the same result as if you used the plain text.
Unfortunately, as the saying goes, in theory there should be no difference between theory and practice, but in practice there is.
Sometimes application will put different text in the RTF than in the plain text. For example, if you copy an entry from a styled list, the plain text might have just the characters, and the styled text might also have a bullet character at the front (or vice versa).
When you use any action in Keyboard Maestro that requires only plain text, it will read the plain text version of the clipboard (eg Filter Text: Remove Styles, or Set Variable to %Current Clipboard%).
When you use any action that can deal with styled text, it will read the RTF or other styled text version of the clipboard if possible (eg Set Named Clipboard to styled text %CurrentClipboard%).
However, when Keyboard Maestro creates a clipboard entry (either for a named clipboard or the system clipboard) based on styled text, the result will always be matching plain and styled text, and any other clipboard flavors will be thrown away).
So if you have a situation where the plain text and the plain text of the styled text differ, you can get the plain text of the styled text by reading the clipboard as styled text, and then storing it somewhere (in a named clipboard or the system clipboard), and then (since that will now be clean without discrepancies) getting the plain text of that.
Set Clipboard to Styled Text %CurrentClipboard% Filter Clipboard: Remove Styles
If Keyboard Maestro cannot write to its preferences folder, it should alert you to the problem. Alternatively, if changes you are making to macros, variables, or Named Clipboards or the like are not sticking, the problem is likely caused by incorrect ownership or permissions of the Keyboard Maestro preference folder or its contents. This most often happens after a poor migration or backup restore of the folder.
Quit Keyboard Maestro, and open the Keyboard Maestro Preferences folder - in the Finder, hold the Option key down, select the menu Go ➤ Library, then drill down into Application Support and find the Keyboard Maestro folder.
Select the folder and choose File ➤ Get Info and then look at the Sharing & Permissions section, and ensure it is owned by you and you have Read & Write privileges. If it is not owned by you, you will need to change the owner. If you do not have Read & Write permissions, you need to change that.
Then also look at the contents of the folder and ensure all the files and folders have the correct owners and permissions (you can select multiple files in the Finder and then hold the Option key down and choose File ➤ Show Inspector to look at all of them). Correct the ownership and permissions if necessary.
If you set the Keyboard Maestro Engine Login Item to launch as Hidden, then it is not able to display palettes or dialogs (like the Alert or Prompt For User Input dialogs). Uncheck the “Hide” checkbox in the Accounts → Login Items system preference and quit and relaunch the Keyboard Maestro Engine to resolve the issue. This appears resolved in Mavericks.
If you close the global floating palette it will not repeat until either you relaunch the Keyboard Maestro Engine, or you show it again using the Show/Toggle Global Macro Palette action.
If you wish to briefly hide all the palettes (eg while watching a video), you can use the Conceal Macro Palettes until Application Switch action.
Cross platform apps, including often Adobe apps, and Finale, do not necessarily update or even build their menu bar until the menu is selected with the mouse. When asked for the menus via the accessibility subsystem, the menus are either not there, or not currently correctly built for the context (eg, menus may be disabled or invisible when they should not be).
Options to force the application into updating its menus include:
Often, simulating a click in the menu bar to the right of the Help menu will be sufficient to cause the menus to be rebuild.
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 or this thread
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.
It appears that recent versions of Wacom’s drivers can result in stuck modifier keys (Option, Shift, Command, Control) when used with Keyboard Maestro, either when pressing hot keys or when Keyboard Maestro is simulating keystrokes. See the forum post Keyboard misbehavior triggered by...?.
The Chrome (and Safari) actions work by making AppleScript requests.
Chrome's auto-update mechanism seems to frequently break the AppleScript connections. Alternatively, having multiple versions of Chrome and/or Chrome within a Virtual Machine may cause problems.
Restarting Google Chrome, Keyboard Maestro Engine, or restarting your Mac will usually resolve the broken connection.
Configuring an explicit version for the Google Chrome application by using the Terminal command:
defaults write com.stairways.keyboardmaestro.engine AppleScriptGoogleChromeName "/Applications/Google Chrome.app"
may resolve the issue if it is caused by multiple versions of Chrome.
An alternative cause can be because the actions work by executing the AppleScript via a osascript, and it is possible for all Execute Script Actions are Not Working.
The Safari (and Chrome) actions work by making AppleScript requests.
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.
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.
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.
If you must stay on version 10.10.0-2 for any reason, see the forum topic on possible solutions.
To resolve App Translocation, in the Finder, move the Keyboard Maestro.app anywhere (the /Applications folder is generally the best place for it).
In macOS Sierra, Apple added a strange security feature called App Translocation (sometimes known as Gatekeeper Path Randomization) which means that after downloading an application, if you do not move the resulting application somewhere (anywhere!), the application will be run as if it is located at a randomly chosen path by the system. The consequence of this is that Launch Engine at Login will not work (because the Keyboard Maestro Engine will have a random, different, path each time), and version updates will fail (because Keyboard Maestro cannot replace itself).
Manually moving the application in the Finder will turn off App Translocation. Moving it by other means (eg, PathFinder, Hazel, Keyboard Maestro, whatever) will not remove translocation.
You can determine if an application is running Translocated by looking at it with the Activity Monitor. Double click on the process in the listing to inspect it, and then look at its Open Files and Ports. One of the first entries will be the application executable, and if it is being Translocated it will have a long path, something like this:
/private/var/folders/9t/ld0kwsdn6mx13x87bw01bh_w0000gn/T/AppTranslocation/A5CA1CC2-10E0-4DD2-9962-7E484D2CFFED/d/Keyboard Maestro.app/Contents/MacOS/Keyboard Maestro
If you still cannot get the flag removed, you can use the Terminal command:
xattr -dr com.apple.quarantine "/Applications/Keyboard Maestro.app"
Keyboard Maestro.app is in the Applications folder.