The screen reader won't start, or the voice cuts out
You enabled the screen reader in GNOME Settings, rebooted, and Orca didn't start. Or you ran orca in the terminal and the voice stutters every few seconds. Maybe you are setting up a workstation for a user who relies on AT-SPI, and application windows are invisible to the reader. Fedora ships with Orca, but the accessibility stack involves more than one binary. The screen reader talks to the desktop through AT-SPI, which talks to the applications, and the audio comes from speech-dispatcher. When one link breaks, the whole chain fails.
Log out and back in. Session services don't always pick up configuration changes mid-flight.
What's actually happening
Orca is a screen reader, but it doesn't read pixels. It reads the accessibility tree. Every GNOME application exposes a tree of elements: buttons, labels, lists, and text fields. Orca walks that tree and announces what it finds. The bridge is AT-SPI (Assistive Technology Service Provider Interface). If an application doesn't expose AT-SPI data, Orca sees nothing.
The audio output goes through speech-dispatcher, a system service that manages voices and synthesis backends. Orca sends text to speech-dispatcher, which converts it to audio using a backend like espeak-ng or flite. Fedora enables AT-SPI by default. Orca is installed by default on Workstation. The failure usually happens at the session startup level, the voice backend configuration, or a missing AT-SPI bridge for a specific application.
Modern Fedora includes Firefox with AT-SPI support compiled in. You don't need the firefox-at-spi extension anymore. If you are on an older release or a custom build, check for that extension.
Check journalctl --user -xeu speech-dispatcher. The log tells you exactly which voice backend failed.
Install and enable Orca
Orca might already be installed. Verify the package status first. If it is missing, install it with dnf. The package manager pulls in speech-dispatcher and the default voice backend automatically.
# Check if orca is installed.
# If the output is "package orca is not installed", proceed to install.
rpm -q orca
# Install Orca and its dependencies.
# dnf resolves speech-dispatcher and espeak-ng automatically.
sudo dnf install orca
The most reliable way to enable Orca is through the GNOME configuration database. This persists across reboots and logins. The GUI Settings menu writes to the same database, but the command line is faster and scriptable.
# Enable the screen reader in GNOME settings.
# This writes to dconf and triggers the session to load Orca on login.
gsettings set org.gnome.desktop.a11y.applications screen-reader-enabled true
# Verify the setting took effect.
# The output should be "true".
gsettings get org.gnome.desktop.a11y.applications screen-reader-enabled
If you prefer the GUI, open Settings, navigate to Accessibility, and toggle Screen Reader. The result is identical. The GUI is just a front-end for gsettings.
For immediate testing without logging out, run orca in the terminal. This launches the reader in the foreground. It is useful for debugging, but it stops when you close the terminal.
# Launch Orca in the foreground.
# This is for testing only. It does not persist across sessions.
# Press Ctrl+C to stop Orca when done.
orca
Reboot before you debug. Half the time the symptom is gone after a clean login.
Configure voices and speech-dispatcher
Orca relies on speech-dispatcher for audio. If you hear no sound, or the voice sounds robotic, the user service might be stopped, or the voice backend is misconfigured.
Start the service explicitly. The --user flag targets the user instance, not the system daemon. Accessibility tools run per-user.
# Start the speech dispatcher user service.
# Orca sends text here for audio synthesis.
systemctl --user start speech-dispatcher
# Enable the service to start automatically on login.
# This prevents silence after a reboot.
systemctl --user enable speech-dispatcher
The default voice backend is usually espeak-ng. It provides decent quality and supports multiple languages. If you want better quality, install flite or additional voice packs. dnf handles the dependencies.
# Search for available speech synthesis packages.
# Look for espeak-ng, flite, or festival.
sudo dnf search speech
# Install espeak-ng if it is missing.
# This is the recommended backend for most users.
sudo dnf install espeak-ng
If speech-dispatcher fails to load a backend, check the configuration file. The user config lives in ~/.config/speech-dispatcher/speechd.conf. Never edit files in /usr/lib/. Those ship with the package and get overwritten on updates. Edit /etc/ or ~/.config/.
# Open the user configuration file.
# Add or modify the "DefaultModule" line to switch backends.
nano ~/.config/speech-dispatcher/speechd.conf
Inside the config, look for DefaultModule. Set it to espeak-ng or flite. Restart the service after changes.
# Restart the service to apply config changes.
# The --user flag is required.
systemctl --user restart speech-dispatcher
Trust the package manager. Manual file edits drift, snapshots stay.
Verify the accessibility stack
Orca, AT-SPI, and speech-dispatcher must all be running. Use these commands to confirm the stack is healthy.
# Check if the AT-SPI registry daemon is running.
# Orca cannot function without the registry.
ps aux | grep at-spi-bus-launcher
# Verify speech-dispatcher status.
# Look for "active (running)" in the output.
systemctl --user status speech-dispatcher
# List available voices.
# This confirms speech-dispatcher can load backends.
spd-say -V
If spd-say -V returns nothing, the backend is broken. Install espeak-ng and restart the service.
Run orca --version to confirm the binary is accessible. Better yet, open a terminal and type orca. If it speaks "Terminal", the stack works.
Check journalctl --user -xeu speech-dispatcher. The log tells you exactly which voice backend failed.
Common pitfalls and errors
Orca can fail in specific ways. Recognize the error message to fix the root cause.
Error: Cannot open display
This happens when you run orca in a non-graphical context, like SSH without X11 forwarding. Orca needs a display server to inject into the session.
# Error when Orca cannot connect to the X11 or Wayland display.
# This usually means you are running orca in a TTY or SSH session.
(orca:1234): Gtk-WARNING **: cannot open display:
Run orca only in a graphical terminal. Use xterm or the GNOME Terminal.
No AT-SPI registry found
This means the AT-SPI bridge is missing. This is rare on Fedora Workstation but can happen on minimal installs or custom desktop environments.
# Error when the AT-SPI bus is not running.
# Orca will refuse to start or report no accessible elements.
(orca:1234): AT-SPI-WARNING **: No AT-SPI registry found.
Ensure at-spi2-core is installed. It is a dependency of Orca, but verify if you stripped packages manually.
# Install the AT-SPI core components.
# This provides the registry daemon and bridge.
sudo dnf install at-spi2-core
SELinux denials
SELinux protects the system. Orca runs with the correct context by default. If Orca fails, check the context.
# Check the SELinux context of the Orca binary.
# It should be labeled bin_t or similar.
ls -Z /usr/bin/orca
If you see denials in the audit log, read journalctl -t setroubleshoot. SELinux denials show up there with a one-line summary. Read those before disabling SELinux. Disabling SELinux breaks security and rarely fixes Orca.
Configuration corruption
Orca stores config in ~/.config/orca. If the config is corrupted, Orca might crash or behave erratically. Reset the config to defaults.
# Remove the user config directory.
# This resets Orca to factory defaults.
# Backup the directory first if you have custom keybindings.
rm -rf ~/.config/orca
Restart Orca after removing the config. The directory gets recreated on the next launch.
Backup your ~/.config/orca directory before wiping it. You can always restore your custom keybindings.
Keybindings and navigation
Orca uses specific keybindings to navigate the desktop. The default key is Insert or Caps Lock. If Caps Lock is mapped to Insert, you can use it as the Orca key.
Press Insert + F1 to open the Orca help menu. This lists all available commands. Use Insert + Space to toggle Orca on and off quickly.
If you need to change the keybindings, edit ~/.config/orca/orca-settings.py. This is a Python file. Modify the keyBindings dictionary. Restart Orca after changes.
Use GNOME Settings when you want a persistent, user-friendly toggle that survives updates.
Use gsettings when you are scripting the configuration or working over SSH with X11 forwarding.
Use orca in the terminal when you need to test the reader immediately without logging out.
Use systemctl --user restart speech-dispatcher when the voice cuts out or sounds robotic.
Use rm -rf ~/.config/orca when the configuration is corrupted and Orca behaves erratically.