Troubleshooting

A device can’t find the host

Work down this list. Most of the time, it is the first or second item.

1. Is the host running? On Windows or a Linux desktop, Basalt Host’s icon is in the notification area or tray. On a host with no screen, sudo basalt-host status says is running. In Docker, docker ps lists the basalt container.
2. Is the firewall letting devices through? The host must accept port 7742 (TCP) and 7743 (UDP).
   • Windows: allow Basalt Host on private networks, and make sure your home network is set to Private. See Let Windows Firewall through.
   • Linux: sudo ufw allow "Basalt Host", or with firewalld, sudo firewall-cmd --permanent --add-service=basalt-host && sudo firewall-cmd --reload. sudo basalt-host status says when the firewall is in the way.
3. Are they on the same network? The device must be on the same home network as the host, not a guest network, and not on mobile data.
4. Is a VPN on? A VPN on the device, or on the host, can hide your home network. Pause it and look again.
5. Docker: the container needs network_mode: host for devices to find it by themselves.

If the host still isn’t listed, your network may be stopping devices from seeing each other, as some mesh systems and router isolation settings do. Pair by address instead.

Basalt says the host isn’t running

The device knows its host but can’t reach it. Check that the host computer is on and awake, and Basalt Host is running on it, then work through the list above. A computer that sleeps takes the drive with it: set it not to sleep while plugged in.

Pairing doesn’t work

• The PIN runs out after a few minutes. Choose the host again on the device for a new one.
• “That setup code isn’t right”: check it with sudo basalt-host status. Codes use no letters that look alike, such as O and 0, or I and 1.
• “Too many wrong codes”: after ten wrong tries, the host replaces its code with a new one. sudo basalt-host status shows it.
• The host is already set up: a setup code is only for the first device. Others pair with a PIN, shown in Manage host on a device that manages the host.

A folder won’t open, or isn’t in the list

On a host with no screen, the service runs as its own basalt user, and only sees folders it is allowed to read. Messages like the host isn’t allowed to open it mean exactly that. See Let it read your files.

In Docker, the host only sees folders mounted under /media, and as the PUID and PGID user.

“Port 7742 is already taken”

Another Basalt Host is already running on that computer: perhaps a copy started twice, both the desktop host and the one with no screen, or a container alongside an installed host. Only one can run at a time. Quit or remove the other.

The drive “is no longer there”

The shared drive was unplugged, switched off, or renamed. Plug it back in, and the host shares it again by itself. If its place has changed for good, choose it again: Share a different drive, or in Manage host.

Films aren’t in Movies

• Is Recognise films and series on? It is off until you turn it on.
• Is the scan finished? The host’s settings show Scanning the drive… while it works.
• Is the file named with the film’s title and year? See Name your files. Then choose Scan again.
• Home videos and recordings are left out on purpose: they are in Videos.

No posters

Posters need Download posters on, and the host needs internet access. Titles the default source doesn’t know can be found with a free TMDb key. A title that can’t be matched gets a cover made from its name.

A film stutters on a phone

• Check that Convert video for devices that can’t play it is on, on the host. The player then switches a film the phone can’t keep up with to 1080p.
• A weak Wi-Fi signal slows everything. Try closer to the router.
• The Quality button in the player shows which version is playing, and switches between them.

A device needs pairing again

A device that went back to an older version of Basalt, or had its storage cleared, or was reinstalled, pairs again with a new PIN. Remove its old entry from the host’s device list afterwards.

The device that managed the host is lost

On the host, run sudo basalt-host setup-code --reset (in Docker, docker exec basalt basalt-host setup-code --reset). The next device to pair with the new code manages the host too.

Find the host’s log

The log says what the host was doing when something went wrong:

Still stuck?

Ask in Help and setup, where the community and Refora Technologies answer; if something is clearly broken, open an issue; or write to us. Say which version of Basalt and Basalt Host you have, what each runs on, and what you see. The host’s log helps a great deal; look through it first, and leave out anything you’d rather not share.