Troubleshooting

Fix permissions, missing icons, and input problems.

Start with:

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 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 with the doctor output and relevant logs. Remove personal paths before sharing.