Espanso Not Working? 9 Common Fixes (2026)

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.

Disclosure: we make Lightning Assist, a paid text expander, so Espanso is a competitor of ours. Espanso is free and open source, and every fix below is for Espanso itself — none of them require switching to anything.

Updated 7 September 2026: fix #9 rewritten for Espanso 2.4.1 and Ubuntu 26.04, which no longer ships an X11 session.

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}}"

If silent YAML failures are a recurring issue for your team, a GUI-based snippet editor sidesteps the problem entirely — you edit fields in a form instead of validating indentation by eye.

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

This permission-reset dance is common after every macOS point release. If you'd rather not repeat it, see how Lightning Assist handles macOS permissions (single grant survives system updates).

💡 Spending more time fixing Espanso than using it? Lightning Assist is a graphical text expander with no YAML files, built-in AI commands, and the same Linux support. Try free for 14 days → — no credit card.

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

9. Espanso Doesn't Start on Wayland

On Wayland sessions (the default on Ubuntu, Fedora, and every current GNOME desktop), Espanso needs its dedicated Wayland build and a one-time permission on the binary; without either it fails to start, or starts and never expands (issue #2223).

Fix: Check your session type with echo $XDG_SESSION_TYPE. If it says wayland:

1. Install the Wayland-specific package (espanso-debian-wayland-amd64.deb on Debian/Ubuntu, the Terra RPM on Fedora), not the X11 one.
2. Grant the capability Espanso needs to read /dev/input and write to /dev/uinput: sudo setcap "cap_dac_override+p" $(which espanso). This is the step in Espanso's own Linux install guide. File capabilities are attached to the binary itself, so if expansion stops after an Espanso upgrade, run it again.
3. Run espanso service register and espanso start.

Make sure you are on Espanso 2.4.0 or later (2.4.0 shipped on 21 July 2026, 2.4.1 on 2 September 2026). 2.4.0 added app detection for wlroots compositors (Sway, Hyprland, labwc, Wayfire) and fixed an install failure on Fedora's Wayland session; 2.4.1 added the desktop file and icon on Linux. Even so, Espanso's install guide still labels Wayland support "experimental": non-US keyboard layouts must be set in the config by hand, app-specific matches only work on KDE with kdotool installed, GNOME shows a small flicker with the clipboard backend, and a newly plugged-in keyboard needs espanso restart.

One thing that changed in 2026: "just log into an X11 session instead" is no longer an option on GNOME. GNOME 50 removed the X11 session entirely, so Ubuntu 26.04 LTS — and any other distribution on GNOME 50 — is Wayland-only (X11 apps still run through XWayland, but Espanso's X11 build cannot see keystrokes from native Wayland apps). If Wayland expansion stays unreliable there, the remaining choices are a compositor Espanso handles well (KDE or a wlroots one) or a text expander whose Wayland path is not experimental — see our Wayland text expansion guide.

Still Not Working? Check the Logs

espanso log

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

At a Glance: Espanso vs Lightning Assist

Feature	Espanso	Lightning Assist
Open source	✅	❌ (commercial, 14-day trial)
Pricing	Free / donations	$5.99/mo base (snippets, folders, team sharing). AI features metered via AI Credits, purchased separately.
Cross-platform (Windows, macOS, Linux)	✅	✅
Configuration	YAML files	Graphical editor
AI commands (rewrite, enhance, etc.)	❌	✅ — Team + AI Credits
Push-to-talk voice-to-text	❌	✅ — works on free tier too, consumes AI Credits
Team snippet sharing	❌ (community workarounds)	✅ built-in
Debug experience	CLI (espanso doctor, logs)	GUI status panel

Both ship on Windows, macOS, and Linux. The choice usually comes down to: do you prefer CLI + config files + free (Espanso) or GUI + AI + voice + paid (Lightning Assist).

When Espanso Configuration Becomes a Maintenance Burden

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, no YAML. Download the 14-day free trial — no credit card required.

By default, your snippets expand as you type — no hotkey needed: Lightning Assist ships with As-You-Type Mode turned on. Type your snippet's trigger — the exact text you saved, like ;meeting or meeting — and it expands inline the moment you finish typing it. A leading ; is optional and keeps triggers distinct from normal words. Prefer a deliberate trigger instead? Switch to Hotkey Mode (optional) any time. See all activation modes →

For a detailed comparison, see Lightning Assist vs Espanso.