DocsMore

When something's wrong

Most problems have a short answer. Find yours below.

The wallpaper

The wallpaper is black. Open Motion Player and pick the scene again. If it's still black, the scene might use something your system doesn't have: a web layer needs WPE WebKit on Linux, and everything needs a graphics driver with Vulkan (mesa-vulkan-drivers on most Linux systems). Motion falls back to its built-in scene rather than showing nothing, so a black screen usually means the wallpaper isn't running at all. On Plasma, check the wallpaper type is Motion: right-click the desktop, Desktop and Wallpaper, Wallpaper type.

It stopped moving. It's probably paused on purpose. A window may be maximised or full screen over it, a game or a presentation may be running full screen, the screen may be locked, or you're on battery and On battery is set to Pause. Check Settings, Resting and battery (just Resting on a computer without a battery). If every screen stopped at once, look at the top of Motion Player: Play all means you paused them yourself.

A screen shows a plain dark gradient instead of its scene. The scene kept closing, so Motion gave up on it on that screen: after five crashes in a row, three times it stopped answering, or three times the graphics driver was reset while it played. Before giving up, Motion waits and tries again: 5 seconds after a crash, and 30 seconds after a driver reset, twice as long each time, up to five minutes. Pick the scene again in Motion Player to try it once more, or pick another.

Parts of a scene are missing. When the graphics driver is reset twice within a week while a scene's own shaders are being drawn, Motion stops drawing that scene's shaders on this computer for a week after the last reset, and plays the rest of the scene without them. A shader that keeps the graphics card busy for too long is also left out, for ten minutes. To try the scene's shaders again before the week is out, delete the file stopped-shaders in Motion's cache, then start the wallpaper afresh. On Windows, the file is in %LOCALAPPDATA%\motion-engine: choose Quit in the tray icon's menu, delete it, and open Motion Player again. On Linux, it's in ~/.cache/motion-engine: delete it, then sign out and back in. If the scene is one of yours, see Materials for the limits on shaders.

It's slow or jerky. Lower Sharpness in Settings, or pick a lighter scene. See Battery and performance.

On Android, the wallpaper says Motion couldn't draw this scene. Motion tried to start the scene several times, waiting longer each time, and gave up; it says so on the wallpaper, in the picker's preview and in a notification (under Wallpaper problems). Pick another scene, or restart the phone. If it happens with a scene that came with Motion, send a bug report from the app.

It's using too much power. See Battery and performance.

A scene won't show, and Motion asks about websites. The scene reaches websites, and Motion asks before it shows it. Allow the ones you trust, or refuse them; the scene shows either way, but can't reach the refused ones. Change your answers any time in Settings, Websites scenes reach.

Sound

Scenes don't move to music.

1. Check Hear what's playing is on, in Settings, Sound and pointer.
2. Check the scene does move to sound: in the library, the Moves to sound filter shows the ones that do.
3. On Linux, Motion listens through PipeWire or PulseAudio, and needs pw-record (from pipewire-bin) or parec (from pulseaudio-utils). On Plasma it needs the motion-input package too.
4. On Windows, Motion listens to what Windows plays to your speakers. If Windows won't allow that, Motion uses Stereo Mix instead, if you turn it on: Windows' Sound settings, Recording, right-click, Show disabled devices, then enable Stereo Mix.
5. On Android, the app needs the permission it asks for when you turn Music on. If you said no, turn it on again in the app, or in Android's settings for Motion.

It moves in Studio but not on the desktop, or the other way round. Studio has its own button for this, in the bar under the preview: Sound, Pretend or Muted. Hover over it to see what it's hearing. Pretend is a made-up beat, so a scene that moves in Studio on Pretend won't move on the desktop until music plays.

The beat is off. Motion counts a beat when the bass jumps. Music with a soft or no low end gives few beats. Follow All or Bass instead of Beat for those.

Pointer and clicks

Scenes don't follow my mouse. Check Scenes can follow the pointer is on in Settings, Sound and pointer. On Plasma, install motion-input. On Android, check Touch is set to Follows your finger.

Clicks do nothing. Clicks only reach the scene on the desktop itself, not through windows. Some layers only answer clicks with a setting on: Burst when clicked, Clicks splash, Burst where clicked and the like. See The pointer, clicks and time.

In Studio, clicking the preview moves layers. That's editing. Turn on Try it, in the bar under the preview, to click the scene as you would the desktop.

Sensors

A reading shows a dash. No reading has come yet. Check, in this order:

1. The scene's page in Motion Player, under Whose sensors: a token needs to be picked.
2. Settings, Sensors: the token is there and connected, and under Readings you can see when each sensor last came.
3. The token on Motion Hub: it can read that sensor, and hasn't been revoked or run out.
4. The device: the token's page on the Hub shows when it last sent.

See Sensors and the watch.

Files and imports

A layer says it's missing. The scene was made with a plugin's layer. Motion doesn't run plugins any more, so that layer draws nothing; the rest of the scene plays as it was. Delete the layer, or put a built-in one in its place.

A .motion file won't open. Motion says why. "It needs a newer Motion" means update Motion. Anything about a damaged or cut-short file means the file didn't arrive whole: download or copy it again.

A web layer shows a blank page, or half of one. A Web project's page stays offline unless the layer's Network is on. And a scene only reaches the websites you've allowed: check Settings, Websites scenes reach.

Still stuck?

Write to [email protected] with what you see and what system you're on: Linux and which desktop, Windows, or Android. Screenshots help. Or send a bug report from Motion, in Settings › Privacy and reports.

Last changed 2 November 2026. Something wrong here? Tell us.