Troubleshooting

Answers to the most frequent problems, and how to collect information for a bug report.

Collect information first

The Log Console

Choose Help → Log Console (⌘⇧L). The console shows every log line since launch and adds new lines live. You can:

• Filter by level or category.
• Search the message text.
• Pause, copy, or export to a .log file to attach to a bug report.

If the console is empty, make sure Capture in-app logs is on under Bòcan → Settings… → Diagnostics.

Console.app

In the macOS Console app, filter by the subsystem io.cloudcauldron.bocan to see all Bòcan log output. File paths and identifiers are redacted from the system log.

Export Diagnostics

Settings → Advanced → Export Diagnostics… writes a diagnostics archive that you can attach to an issue. Read it before you share it.

Report the problem

Open an issue at github.com/bocan/bocan-music/issues. Include the Bòcan version, the macOS version, the steps, and the exported log.

Where Bòcan keeps its data

Data	Location
Library database, cover art, backups	~/Library/Application Support/Bocan/
Crash diagnostic reports, only after you give consent	~/Library/Logs/Bocan/diagnostics/
Preferences	~/Library/Preferences/io.cloudcauldron.bocan.plist
Passwords and service credentials	The macOS Keychain

Ordinary logs stay in memory. A log file exists only after you export one from the Log Console or with Settings → Advanced → Export Diagnostics….

Delete those folders to remove everything Bòcan knows about you. Your music files are not in these folders and are not changed.

Library and scanning

New files do not appear

• Make sure folder watching is on under Settings → Library.
• Run Quick Rescan Library (⌘⌥R). If that does not help, run Full Rescan Library (⌘⌥⇧R).
• Make sure the folder is in the library roots list under Settings → Library.

A track is greyed out or marked missing

The file moved, was renamed outside Bòcan, or is on a drive that is not connected. Connect the drive or put the file back, then rescan.

Search finds nothing, or finds old results

Use Settings → Advanced → Rebuild Full-Text Search Index.

A file does not play

• Look at Supported Formats and the list of formats Bòcan does not play.
• Files with DRM (Apple FairPlay, WMA DRM) never play.
• Surround files play folded to stereo. Dolby Atmos objects are not rendered.

Tags do not save

• Bòcan 2.15.0 and later save tags correctly on external drives and network shares. Update if you have an older version.
• The error message names the file and the cause, for example a read-only file.
• A cover-art change does not write to your audio files unless you turned on embedding under Settings → Library.

Playback

Loud and quiet songs in one album play at the same level

Album gain was added in 2.19.0. Run Tools → Compute Missing ReplayGain to fill in the album gain from the values you have. No song is measured again.

A surround file has the wrong volume

Loudness values measured before 2.16.0 for files with more than two channels were wrong. Analyse those songs again.

Crossfade does not happen

• Crossfade applies to songs stored on your Mac only. Streams and podcasts do not crossfade.
• With Keep gapless within albums on, songs from the same album play without a gap and without a crossfade.

No sound after a change of output device

Bòcan follows the system default output and reconnects at the sample rate of the new device. If there is no sound, make sure the correct device is selected in System Settings → Sound, then pause and play.

Mouse and keyboard

The back and forward mouse buttons do nothing

Logi Options+ intercepts the thumb buttons. See Mouse Buttons for the correction.

A shortcut does not work

Look at Keyboard Shortcuts. A different app or a system shortcut can take the same key combination.

Subsonic servers

The dot next to each server shows its state:

Dot	Meaning	What to do
Orange	Authentication failed	Enter the username and password again under Settings → Sources
Red	Unreachable or server error	Check the URL, the network, and that the server is running. Then look at the server's own log
Grey	Not checked yet	Wait, or use Test Connection

• Use Test Connection in the server editor under Settings → Sources.
• For a server with a self-signed certificate, turn on the self-signed TLS option for that server.
• When a server is offline, click Retry now in the orange banner.

More detail is in Subsonic Servers.

Podcasts

A show stopped refreshing

• A feed served over plain http is accepted only from a computer on your home network.
• If a show that you added before 2.15.0 stopped updating, add it again by its address. It continues with its episodes and settings.

Downloaded episodes use too much disk space

Open Tools → Library Summary (⌘⇧Y), select the Podcasts tab, and use Reap Now. A retention policy does not free disk space. It only shortens the episode list, and downloaded, played, and in-progress episodes are always kept.

Scrobbling

• Open Show Recent Scrobbles (⌘⌥⇧S) to see the last 50 tracks and their submission status.
• Settings → Scrobbling shows the pending count and has Retry Failed and Discard Failed.
• A track scrobbles only if it is at least 30 seconds long and you played 50% of it or 4 minutes. Paused time does not count.
• Radio stations never scrobble.

Phone Sync

See the Problems section of Phone Sync.

Updates

• Choose Check for Updates… from the Bòcan menu to check now.
• If you installed with Homebrew, brew upgrade --greedy bocan does the same. A red mark next to the cask name in brew info is not an error.

Backups and recovery

• Settings → Advanced has iCloud Drive backups (three rolling snapshots) and local backups (1 to 20 snapshots) of the library database.
• After a crash, a banner offers Recover or Start Fresh for the queue.
• Tag edits have an edit log and a backup ring, so a bad edit can be undone.