---
title: Troubleshooting
description: Fix permissions, missing icons, and input problems.
---

Start with:

```bash
pnpm exec filedom doctor
```

## Icons don't appear, or nothing moves

Enable Finder under System Settings → Privacy & Security → Automation for the
app running FileDOM, then run `doctor` again.

## Game controls don't respond

Grant Accessibility access to the app running FileDOM, then relaunch that app.
If only certain keys fail, check keyboard remapping tools such as Karabiner.

## Icons go blank or flicker during animation

Prepare each artwork variant before play and move sprites between positions.
[Stage & Sprite](/docs/reference/components/stage) manages the prepared files.

## Parked sprites show next to the park

The park cover is sized to one icon cell plus its label band at the park point.
Check that every parked sprite shares that park and that the metrics passed to
`StageProvider` match the current display.

## Icon size or grid spacing didn't take

Set view options before creating game files, and check the configured icon size
and display metrics.

## My Desktop files disappeared during a session

Quit normally and wait for restoration.

Sessions do not move your files. They set the macOS hidden flag on them in
place, so the files stay in `~/Desktop` the whole time. To see them right away,
press Cmd+Shift+`.` on the desktop, or run `chflags nohidden ~/Desktop/*` (this
also reveals any items you had hidden yourself). After a crash, the next session
recovers the journal and reveals what the crashed run hid before it hides
anything new. If files still look missing, keep the journal and the logs:

- Finder Mode: `~/.finder-mode-stash`
- FileDOM sessions: `~/.filedom-desktop-stash`

## Loading is late, or prepared labels flash blank

Keep initial setup inside the session's readiness lifecycle instead of
revealing the board after a fixed timeout.

## Unexpected clicking or incorrect card order

Check sprite overlap and placement order. Include a recording and the run's
logs when reporting the problem.

## Quit leaves files behind

Await session cleanup before the process exits. Calling `process.exit()`
straight after unmounting cuts cleanup short.

## Reading the log

Logs are in `~/Library/Logs/filedom/`, one file per process. Use the latest run
that matches your session.

## Still stuck?

[Report an issue](https://github.com/methodacting/filedom/issues) with the doctor
output and relevant logs. Remove personal paths before sharing.