troubleshooting

Espanso Not Working? 8 Common Fixes (2026)

By Lightning Assist TeamMarch 29, 20268 min read
espansotext-expandertroubleshootinglinuxwindowsmacos
Share:
Lightning Assist blog post featured image

Espanso is a powerful open-source text expander, but its YAML-based configuration means things can go wrong in ways that aren't obvious. Here are the most common reasons Espanso stops working — and how to fix each one. For official CLI and paths, see the Espanso documentation.

1. Espanso Is Not Running

The most common cause: the Espanso service isn't started.

Fix:

espanso start

Check if it's running:

espanso status

On Linux with systemd:

systemctl --user status espanso
systemctl --user start espanso

2. YAML Syntax Error in Your Config

Espanso silently fails when a config file has invalid YAML. One misplaced tab or colon breaks the whole file.

Fix: Run the config doctor:

espanso doctor

Common mistakes to check:

  • Using tabs instead of spaces (YAML requires spaces)
  • Missing quotes around text that contains special characters like :, #, or \
  • Indentation that's off by one space
  • A replace: value that starts with { — this must be quoted: replace: "{{clipb}}"

3. Espanso Not Working in a Specific Application

Some applications — especially Electron apps (VS Code, Slack, Discord), terminals, and apps with custom input handling — don't receive Espanso's simulated keystrokes correctly.

Fix on Linux: Make sure you're using the correct injection backend. Edit ~/.config/espanso/config/default.yml:

backend: Auto

Try switching between Auto, Clipboard, and Inject:

backend: Clipboard

Fix on Windows: Run Espanso as administrator, especially for apps that run with elevated privileges.

Fix on macOS: Go to System Settings → Privacy & Security → Accessibility, remove Espanso from the list, then re-add it.

4. Missing Accessibility Permissions (macOS)

Without Accessibility permissions, Espanso can't monitor keystrokes or simulate text output.

Fix:

  1. Open System Settings → Privacy & Security → Accessibility
  2. Find Espanso in the list
  3. Toggle it off, then back on
  4. Restart Espanso: espanso restart

5. Trigger Not Firing — Wrong Trigger Type

By default, Espanso uses word triggers that only expand after a word separator (space, newline, punctuation). If you're typing your trigger in the middle of a word, it won't expand.

Fix: Check your trigger type in the match file. Use word: false if you want to trigger anywhere:

matches:
  - trigger: ":sig"
    replace: "Best regards,\nYour Name"
    word: false

Or use the regex trigger type for more control:

matches:
  - regex: ":sig$"
    replace: "Best regards,\nYour Name"

6. Espanso Not Working After System Update

OS updates — especially on macOS and Linux — often revoke accessibility permissions or break the system service.

Fix:

  1. Re-grant Accessibility permissions (see Fix 4 for macOS)
  2. On Linux, re-register the systemd service: espanso service register
  3. On Windows, check that Espanso is still in the startup list

7. Config File in Wrong Location

Espanso looks for config files in specific locations. Placing your .yml match files in the wrong folder means they'll never be loaded.

Default config locations:

  • Linux: ~/.config/espanso/
  • macOS: ~/Library/Application Support/espanso/
  • Windows: %APPDATA%\espanso\

Match files must be in the match/ subdirectory. Run espanso path to see the exact paths for your system.

8. Espanso Conflicts with Another Application

Some applications or accessibility tools register global hotkeys that conflict with Espanso's own key monitoring.

Fix:

  • Temporarily disable other accessibility tools, screen readers, or hotkey managers
  • Check Espanso logs for errors: espanso log
  • Try running espanso doctor for a full diagnostic

Still Not Working? Check the Logs

espanso log

This shows exactly why Espanso is failing. Look for permission errors, parsing errors, or backend issues.

When Espanso Is Too Complex to Configure

Espanso's YAML configuration gives you power but adds real friction — especially when getting started, debugging silent failures, or collaborating with a team that isn't comfortable with config files.

If you're spending more time fixing Espanso than actually using it, consider Lightning Assist — a graphical text expander for Windows, Mac, and Linux with a full GUI, built-in AI commands, push-to-talk voice typing, and team snippet sharing. No config files. 14-day free trial, no credit card.

For a detailed comparison, see Lightning Assist vs Espanso.

Related Articles