Troubleshooting

Symptom-first. Crew problems first, box problems at the end.

"I can't join"

• The join page never loads — you're not on the event network. Join the Wi-Fi named on the poster, then scan again. Some phones cling to mobile data; turning it off for a minute forces them onto the venue Wi-Fi.
• "That name is taken and the PIN doesn't match" — the name you typed exists and the PIN isn't its PIN. If it's yours, you've misremembered your PIN: ask an admin to reset it. If it isn't yours, pick another name.
• The event PIN is rejected — PINs change occasionally; read it off the current poster or the /connect screen, not a photo from yesterday.
• "Too many attempts" — the box rate-limits guessing. Wait a minute.
• The app opens, but the banner says "Connecting" — crewbox is installed on your phone, so it draws itself from your phone's own storage before it has spoken to anything. That banner means the box isn't answering. Give it half a minute and the banner turns into Still connecting… Why? — tap it and the app walks you through the likely causes for your phone.

The one worth knowing in advance, on an iPhone: glance at the Wi-Fi symbol in the status bar. Gone means iOS decided this network has no internet and quietly moved you to mobile data, which cannot reach the box. Turn mobile data off for a minute and it comes straight back — and tell whoever runs the box, because there's a proper fix.

On Android in a browser, or with crewbox added to the home screen from one, the sign is an exclamation mark on the Wi-Fi symbol: Android decided this network has no internet and is sending the browser's traffic over mobile data. Turn mobile data off and it comes straight back. The Android app doesn't need that: it stays on the crew Wi-Fi by itself.

Nothing is lost while this lasts. Everything you can see is on your device, and anything you send is queued and delivers the moment the box is back.

"The box at … has changed"

The box at that address is running another event than the one your device has open: a spare box that started afresh, or the next event's box. Your device keeps the event you had, sends the new box nothing of it, and waits for you to tap Open it. After you join, it offers to bring your work across when whoever runs the box has said it carries your event on, and otherwise Bring its work here, beside the old event in Your boxes, does it. More in Getting connected.

"I can hear voice but nobody hears me"

That's the HTTPS microphone rule — the voice bar will say listen-only. See the voice page. Quick fixes: use the Android app, or ask whoever runs the box whether HTTPS is set up.

If you're not listen-only but still silent: open the voice bar's gear and watch the mic meter while you speak. Flat bar → wrong mic selected, or the browser was denied mic permission (check the padlock icon in the address bar).

"I'm not getting alerts"

• Check the bell in the sidebar isn't muted.
• Backgrounded browser alerts need notification permission — the browser asks once; if it was refused, re-enable it in site settings.
• Check the channel's own bell: every channel starts at Mentions, so ordinary messages don't buzz until you pick All messages.
• Changeover calls need the stage followed in the running order.
• iPhone, locked, no internet: not yet. Ordinary iPhone notifications come through Apple's servers, unreachable from an offline event network. Crewbox's way round it waits on Apple's permission (Phones and platforms). Give Android phones to roles that must not miss a call — the Android app holds its own connection to the box and buzzes on the lock screen, entirely on the LAN.
• Android, after a restart: the alerts come back by themselves once the phone is unlocked. If they don't, open the app once.

"My message says sending… forever"

The box is unreachable from your device. The message is safe and will deliver when the connection returns — don't retype it. If everyone nearby has the same problem, the box or the Wi-Fi is down; if it's just you, walk closer to an access point and watch the banner.

If it also says Not saved on this phone, your device refused to keep it, usually because it is out of space. It still delivers when the connection returns, but only while crewbox stays open: closing the app loses it. Free some space before you write anything else.

"A channel looks empty" / "someone's messages are missing"

If the filter bar is open, close it — a filter narrows the view to what's loaded on your device, and it clears itself when you switch channels precisely so this state can't linger. For history beyond what's loaded, use search (⌘K), which asks the box for everything.

"Sheet not found" or "Plot not found"

The box saves every sheet, plot and screen map that passes through it, so this usually means it has been deleted, or the link you followed came from a different box. It can also be one this box has never had: one made on a phone that hasn't reached the box since, or one from before the box was started again with a fresh database. Ask whoever made it to open it with the app connected: it appears on your screen as soon as they do.

"The reload pill does nothing"

New version available — Reload occasionally needs a few seconds while the new version finishes downloading. Tap it again. If it persists, close and reopen the app — nothing unsent is lost either way.

In the iPhone and Android apps, New version ready — Reload appears only once the new version is already on the phone, so there is nothing to wait for. If the app goes back to the version you had, by itself or with a message that the phone couldn't open the new one, the new version didn't start on this phone. The app carries on with the one it has and doesn't offer that version again. The app also needs about 50 MB free on the phone to take a new version, and offers none until it has the room.

"The lighting plot shows no levels"

The drawings only colour by desk output when Levels is switched on in the live bar — it's off by default because levels are the expensive part. No live bar at all means this box isn't listening to a lighting network — that's an operator setting (Admin → Lighting network).

"The Network module says Not watched"

Honest reporting, not a fault: the box wasn't told to watch that network. The card says what to change; it's an operator switch, not something in the app.

For the box's operator

• The box won't start / port already in use — a box is already running on that machine; crewbox --status shows it, crewbox --stop stops it.
• Crew can't reach the box by name — the venue DNS doesn't answer for your hostname. Admin → This network flags this and offers a ready-made crewbox-dns.conf download for the router.
• The name resolves, but to a public address — you have a DNS override somewhere and it's stale: it's still pointing at last event's IP, or at the public website. Check from a machine on the crew network:

``sh curl -v https://chat.example.com:8787/ # what address did it try? ``

A 216. or any other public-looking address means the override lost. Update the router's address=/name/ip line to the box's current IP — it changes with the DHCP lease unless the box is reserved — and restart dnsmasq. On a MikroTik, run a fresh crewbox-dns.rsc (Download for MikroTik) again: it replaces the old entry. On your own OpenWrt router, Admin → This network → Keep the router pointed at this box does this for you whenever the address changes; see Admin. A box's IP is on its own terminal banner and in crewbox --status.

• The name resolves correctly on phones but not on the box's own laptop — that laptop is asking the wrong resolver. macOS picks its DNS server from the service order, not from which network you're using: if a USB tether or Wi-Fi sits above the crew Ethernet in System Settings → Network → … → Set Service Order, every lookup goes to that one, which has never heard of the box. Drag the crew adapter to the top, or add a line to /etc/hosts — that beats DNS entirely and survives reordering:

``sh echo "192.168.200.77 chat.example.com" | sudo tee -a /etc/hosts ``

• The readiness list says "Phones stay on this Wi-Fi" is on port 8880 — working as designed. Port 80 needs root and the box hasn't got it, so it took an unprivileged port; phones only ask on 80, so it needs one redirect rule. Admin → This box → Download port 80 config has it, filled in for this machine. Don't test the rule with curl from the box itself — macOS won't redirect a machine's traffic to itself, so it fails while working.
• iPhones show the app but never connect — iOS has judged the crew network internet-less and fallen back to mobile data. This is the single most confusing failure in the product because the phone still shows as joined. Admin → This box has a Phones stay on this Wi-Fi row; see the full explanation and fix.
• Androids in a browser never connect, and the Android app does — the same judgement: with mobile data on, Android keeps the crew Wi-Fi joined but sends a browser's traffic over mobile data, and the box answering the phones' tests doesn't change that for Android. Mobile data off fixes it, and so does the Android app, which keeps its traffic for the box on the crew Wi-Fi (on Android).
• An Android phone doesn't rejoin the crew Wi-Fi by itself — Android may stop joining a network by itself once it has found no internet there, or once somebody has answered No to its question about it. Join it again from Settings → Wi-Fi, or scan the Wi-Fi code on the join poster. On a Samsung, Switch to mobile data (Settings → Connections → Wi-Fi → ⋮ → Intelligent Wi-Fi) takes a phone off a Wi-Fi it judges unstable; turn it off on crew phones that keep leaving.
• An Android phone reaches the box by its address, but not by its name — Private DNS set to a provider's name, in the phone's network settings, sends every lookup to that provider, over an internet the crew Wi-Fi hasn't got. Set it to Automatic at the venue, or use the box's address.
• Setup page gone — /setup closes forever once the first person joins. Everything on it lives on in the admin panel. Lost the admin password as well? On the box, Open the admin panel in the Crewbox menu or crewbox --admin gets you in without it, once; set a new one under Admin → This box. The ADMIN_PASSWORD environment variable and a restart still override it too.
• Everything else — the readiness list in Admin → This box exists precisely for "what's wrong and what do I do": every red or amber row carries its own fix.