Nothing expands at all
Check these in order:
Is expansion on? If the menu bar icon has a small ✕, expansion is off. Choose Enable Expansion from its menu.
Does Shorthand have keyboard access? Open the menu bar menu. ✓ Keyboard access OK means it does. If you see ⚠︎ No Accessibility access — snippets can’t expand. Fix… or ⚠︎ Keyboard access blocked by macOS — Fix…, see below.
Is Shorthand locked? If the menu shows 🔒 Shorthand is locked — Unlock…, expansion may be paused until you unlock. See below.
Is Secure Input on? A warning triangle as the menu bar icon means another app is blocking all text expanders. See Secure Input.
Is Shorthand paused in this app or website? If the menu shows ⏸ Paused here: …, it’s on your blocklist, or (⏸ Paused here: waiting for your answer) Shorthand is waiting for you to answer “Use Shorthand in …?”. See below.
Are you typing in a Shorthand window? Abbreviations never expand inside Shorthand’s own windows (so you can type them in the editor), or in its search and AI Actions panels. Try TextEdit.
Did you type the delimiter? By default an abbreviation expands when you type a space, Tab, Return, or Escape after it. See Delimiters.
Accessibility permission
macOS must allow Shorthand to see your keystrokes, or it can’t notice abbreviations.
Open System Settings ▸ Privacy & Security ▸ Accessibility. (Shorthand’s Grant… button in Settings ▸ General ▸ Permissions opens it for you.)
Turn on the switch next to Shorthand.
Turning the switch off while Shorthand is running is safe: Shorthand stops its keyboard monitor right away. (Before 1.5.4, doing this could freeze typing and clicking until Shorthand was quit. If you see that on an older version, update.)
The switch is on, but snippets still don’t expand
macOS is remembering an older copy of Shorthand, for example from before an update or rebuild. The switch looks on, but it belongs to the old copy.
Click the Shorthand menu bar icon and choose the ⚠︎ … Fix… item. Or use Settings ▸ General ▸ Permissions ▸ Reset Permission & Ask Again.
Shorthand clears its old permission entries, asks macOS again, and opens Accessibility settings.
Switch Shorthand on. Within about two seconds the menu shows ✓ Keyboard access OK. You don’t need to restart.
Settings ▸ General ▸ Permissions shows what macOS actually reports: Accessibility (macOS) and Keyboard monitor running should both be green. Show Diagnostics Log reveals a small log of these changes. The log never contains anything you type.
If you’d rather do it by hand: in Accessibility, select Shorthand, click –, then + to add it again and switch it on. Turning the switch off and on isn’t enough.
Secure Input is blocking expansion
While you type a password, macOS turns on Secure Input, which hides keystrokes from every other app, including all text expanders. Some apps (password managers, Terminal’s “Secure Keyboard Entry,” some banking sites) leave it switched on by mistake.
When this happens, the menu bar icon becomes a warning triangle and the menu shows ⚠︎ Secure Input is on (app name) — expansion blocked.
Note the app named in the warning.
Switch to it, finish or cancel any password entry, and (in Terminal) turn off Secure Keyboard Entry in its app menu.
If the warning stays, quit that app. Expansion resumes on its own once Secure Input is off.
Snippets expand twice
If the menu shows ⚠︎ TextExpander is also running — snippets may expand twice, both apps are reacting to your abbreviations.
Make sure your snippets are imported (Importing).
Quit the other app, or turn off its expansion from its own menu.
Remove it from System Settings ▸ General ▸ Login Items so it doesn’t start again next time.
Snippets don’t expand in one app or website
First, check whether Shorthand is paused there. Click the Shorthand icon in the menu bar while you’re in that app or on that page. If it shows ⏸ Paused here: …, the app or website is on your blocklist (password managers are blocked from the start). Choose Allow Shorthand Here to let snippets work there again, or edit the lists in Settings ▸ Privacy.
If it says ⏸ Paused here: waiting for your answer, the app is new to Shorthand and the question “Use Shorthand in …?” is on screen. Click Allow (or choose Allow Shorthand Here); if you don’t answer, Shorthand allows it after about 12 seconds. See The first time you use an app.
On a website you haven’t blocked, check whether the page includes a sign-in box from a blocked site (a bank login, for example). Shorthand checks every part of the page, so that also pauses it.
If it isn’t paused, Shorthand checks app rules in this order: the snippet’s own Expand in setting, then its group’s, then the default in Settings ▸ Expansion ▸ Expand snippet groups in.
Select the snippet. Is Expand in set to No Applications, or to Only These Applications… without that app?
Select the snippet’s group. Check its Expand in setting the same way, and make sure Enabled is on.
Check Settings ▸ Expansion ▸ Expand snippet groups in; the app may be on an exclusion list.
If all those are fine, the app may be using Secure Input (see above) or may not accept pasted text; try Search Snippets… from the menu bar to insert the snippet manually.
More on Per-App Snippets.
One snippet doesn’t expand
Is the group enabled? Disabled groups show a folder with a minus sign in the sidebar.
Case: with Case Sensitive, Sig won’t trigger sig. Try Ignore Case.
What’s before it: the group’s Expand after rule may require a space before the abbreviation. If you type it straight after a letter, choose All characters. See Expand after.
Conflicts: an abbreviation shown in orange is the start of another abbreviation (e.g. addr and addr2). With Immediately when typed the shorter one always wins. Rename one, or use a delimiter mode.
You clicked or used arrow keys while typing the abbreviation. That resets what Shorthand has seen; retype it in one go.
The expanded text looks wrong
Your clipboard changes after expanding
Shorthand pastes snippets and then puts your clipboard back. If a slow app pastes the old clipboard, raise Restore delay in Settings ▸ Expansion (default 0.40 s).
Formatting is lost or odd in a web app such as Gmail
Turn on Include HTML for formatted snippets (web apps like Gmail) in Settings ▸ Expansion. Turn it off if an app pastes stray styling.
A % code is typed literally
It may be misspelled, or it contains a % or colon inside. See Rules worth knowing.
The first letter is capitalized unexpectedly
That’s Adapt to Case of Abbreviation (you typed a capital) or Capitalize new sentences in Settings ▸ Options.
Script snippets time out or insert nothing
A script that runs longer than 10 seconds is stopped. Whatever it had printed by then is inserted, which is often nothing. Make the script faster, or have it do slow work in the background.
Only normal output is inserted. Error messages are ignored, so a broken script inserts nothing. Test it in Terminal or Script Editor first.
If your Mac beeps and nothing is inserted, Run script snippets (AppleScript, shell, JavaScript) is off in Settings ▸ Expansion.
An AppleScript that controls another app may trigger a macOS permission prompt the first time; click OK.
See Script Snippets.
AI errors
AI messages appear in a small floating notice near your cursor.
Message
What to do
Set up an AI provider in Settings → AI.
No provider is ready. Follow Quick setup.
No API key saved for provider. Add it in Settings → AI.
Paste your key in Settings ▸ AI and press Return.
Provider rejected the API key (401). or (403).
The key is wrong, revoked, or the account has no credit. Make a new key on the provider’s site, paste it, and click Test key & load models.
Provider error 429: …
Rate limit or quota reached. Wait a minute, check your billing, or set a fallback provider.
Provider error 404: … (or a “model” message)
The model id doesn’t exist for your key. Click Test key & load models and pick one from the list.
Couldn’t reach provider: …
No internet connection, or (for a local model) the server isn’t running.
The custom provider needs a model name and an https:// URL (or http://localhost).
Fill in the model id and fix the Base URL; see Custom and local providers.
Provider declined this request (…).
The model refused. Rephrase the request. The fallback provider is deliberately not tried for refusals.
Provider returned no text.
Try again, or try another model.
Two messages joined by “Fallback:”
The main provider failed, the fallback was tried once, and it failed too. The first message is the main provider’s, the second the fallback’s.
Select some text first, then press the AI Actions hotkey.
AI Actions works on selected text. Select it, then press ⌃⌥A.
If a %ai snippet fails, Shorthand types your abbreviation back so nothing is lost.
If a model rejects one of Shorthand’s optional request settings, Shorthand automatically retries once with a simpler request to the same provider. That retry is not the fallback.
Library and settings problems
“Shorthand couldn’t read your snippet library.” The damaged file was moved aside (nothing deleted). Restore a backup: Settings ▸ General ▸ Backup ▸ Restore…. See Restore.
Deleted something by mistake? Press ⌘Z in the main window or click Undo in the notice that appears, or select Trash in the main window’s sidebar and click Put Back. See The Trash. If it has already left the Trash, restore a backup.
macOS keeps asking for Keychain access. See Keychain prompts.
“Library updated by an older Shorthand on another Mac.” Another Mac sharing your sync folder is still on Shorthand 1.2. Your Trash and tags were kept; update Shorthand on that Mac. See Sync.
The menu bar icon is missing. Open Shorthand from Applications (this opens the main window), then turn on Show Shorthand in menu bar in Settings ▸ General.
Shorthand asks for a password or recovery key at launch
The window says Your snippets are encrypted and asks for your Shorthand password or recovery key. Your files are encrypted, but this Mac doesn’t have the key in its Keychain: for example, it’s a new Mac, or the Keychain was reset.
Type your Shorthand password or your recovery key in Password or recovery key.
Click Unlock.
It’s needed once: Shorthand keeps the key on this Mac from then on. Until you unlock, Shorthand doesn’t save or back up anything and snippets don’t expand, so nothing is overwritten. If it says That isn’t right. Try again., check the password, or use the recovery key instead. See Forgot my password and Syncing between Macs.
Shorthand is locked
If the menu bar menu shows 🔒 Shorthand is locked — Unlock… instead of your snippets, the app lock is on. Choose that item, or open any Shorthand window, and unlock with Touch ID, your Apple Watch, or your password. Shorthand locks again when the Mac sleeps or the screen locks, or as set in Settings ▸ Security ▸ Lock again. To stop locking, turn off Require unlock to open Shorthand there.
Help never locks, so you can keep reading.
Snippets don’t expand: the lock is pausing expansion
With Pause expansion while locked on, nothing expands while Shorthand is locked. At login a bubble says Shorthand is locked. Snippets expand after you unlock.
Click Unlock… in the bubble, or choose 🔒 Shorthand is locked — Unlock… from the menu bar icon, and unlock.
To keep snippets expanding while Shorthand is locked, turn off Pause expansion while locked in Settings ▸ Security.
Snippets also don’t expand while Shorthand is waiting for your password or recovery key (see above), or after another Mac encrypted your synced library, until you click Unlock… in the bubble that appears.
Forgot my password
Type your recovery key wherever Shorthand asks for your Shorthand password.
If Shorthand still opens on this Mac, click Remove Password… in Settings ▸ Security, then Set a Shorthand Password….
Without the password or the recovery key, encrypted files can’t be opened on a Mac that doesn’t already have the key. See Forgot your password?
Related: Security & Encryption · Privacy, Blocklist & Permissions · Abbreviations & Expansion · Support Shorthand