Troubleshooting

Common problems and how to fix them. If yours is not here, ask in Q&A.

Most answers start in the board's log. On a Mac with the app it is ~/Library/Logs/VitalAIze/board.log, and built from source it is ~/Library/Logs/wallboard.log. On Linux, run journalctl --user -u vitalaize.

The iPad cannot reach the board

• Check that both are on the same Wi-Fi.
• Check that the firewall allows incoming connections on the board's port (4747 unless you changed it): on a Mac in System Settings, Network, Firewall; on Linux with ufw, sudo ufw allow 4747/tcp. A hub that takes collectors also needs the link's port open (4748 unless you changed it); collectors use the board's port too, to pair and to ask whether they were removed.
• Use the address the board printed when it started (VitalAIze shows it on a Mac), not localhost.

"Add ?token= ..." on the page

You set a board password (token), and the address is missing it or has a different one. Add /?token=<your token> to the end of the address once; after that the browser remembers it. Changing the board password signs every device out, so each needs the new one once.

The Settings page will not open

Without a board password, the Settings page opens only in a browser on the machine that runs the board. Open it there, or set a token (see Settings).

A panel shows "stale" in red

It says why. Usually gh or claude is signed out, or the machine lost its connection. Sign in again (gh auth login, or run claude once), and the panel catches up on its next round. The rest of the board keeps working meanwhile.

No alerts

The board's log says which channel failed and why.

• Messages: check the phone number, that the Messages app is signed in on the board's Mac, and that macOS allowed the board to control Messages (System Settings, Privacy & Security, Automation). If your number is not on iMessage, set Send as to SMS, and turn on Text Message Forwarding on your iPhone.
• Slack, ntfy or Pushover: check the address, topic or keys, and that the board's machine can reach the internet.
• A session on another machine: check that the machine is connected: it shows under Connected machines on the hub's Settings page, with "Seen now". See Connecting other machines.
• Codex: Codex alerts need the one-time step on the Codex page. See the next section.

See Alerts for the setup of each channel.

The board says Over budget, or no budget alert comes

• No strip and no alert: budget limits need the archive. With a limit set and the archive off, the strip says no limit is checked; turn archive.enabled back on in settings.exs.
• No alert, but the strip shows: under Budget in Settings, check that the channel is switched on for budget alerts, and that it is set up under Alerts. Until a channel takes the alert, the board tries again every minute; the log says which channel failed.
• The strip came late: a busy session on the hub counts only once it pauses for archive.settle_seconds (2 minutes).
• One alert for each limit, per day or week. It does not repeat. See Alerts.

Shipped on Trends says it can't read pull requests

• "Can't read pull requests in acme/api: the GitHub sign-in is not allowed to": the account gh is signed in as cannot read that repository's pull requests. Sign in as one that can (gh auth login), or stop following the repository.
• "Can't read pull requests in acme/api right now, trying again every 5 minutes": GitHub did not answer. It tries again by itself.
• "Loading…" stays until each repository's pull requests have been read once.

A Codex session never shows Needs you

• The hook must be in ~/.codex/hooks.json on the machine where Codex runs (see Codex).
• Codex must trust the hook. Codex skips a new or changed hook until you trust it: open Codex, type /hooks, and trust the VitalAIze entries. Do this again after you change hooks.json, and after you upgrade VitalAIze, since an upgrade can replace the hook script.

A card says Needs you after I already answered

See Known limits for the cases where a Codex card stays longer than it should.

A machine will not pair

The new machine says why:

• "No hub found on this network." Give it the hub's address. Some networks, such as guest Wi-Fi, block the announcements a hub sends. On a Linux hub they need avahi-utils, and archive.advertise must be on (it is by default).
• "That board does not take collectors." On the hub, open its settings (the VitalAIze app, or bin/vitalaize setup), turn on Take collectors, and ask again. See Settings.
• "Nobody approved the code in time." A code is good for 10 minutes. Start again for a new one.
• "The hub has too many requests waiting, or one from this machine or under its name." The mailbox holds 5 requests, and one for each name. Wait a minute and try again.
• "The hub's owner refused this machine." Someone tapped Refuse in the mailbox.
• The code never shows in the hub's mailbox. The machine is talking to something that is not your hub. Stop, and give it your hub's address.

The Approve button is greyed out

With no board password, only a browser on the hub's own machine can approve. Open the board there, at http://localhost:4747/, or give the board a password. See Connecting other machines.

A card is marked stale

The hub has lost the link to that card's machine. The note on the card says since when. Check that the machine is on, awake and on the same network. The card comes back to life by itself when the machine reconnects, and nothing is lost: the machine keeps what it could not send.

Sessions from another machine never arrive

• On the hub's Settings page, look at Connected machines. A machine that is listed but "not connected yet" or "Never seen" has paired but is not streaming: check that the collector is running there, and that the hub's firewall allows the link's port (4748).
• A machine that is not listed has to be paired. See Connecting other machines.
• If someone tapped Disconnect for it, pair it again.

A collector says the hub is not answering, but the hub is up

If you tapped Disconnect for that machine on the hub while the machine was off or out of reach, the hub now turns it away, and all the machine sees is a connection that fails. From 0.4.0 the machine asks the hub whether it was removed after a few failed tries, and within about three minutes says the hub removed it. A machine still on 0.3.0, or one removed after the board's port changed and before it connected again, never finds out and keeps trying. Pair it again: Pair again… in the app, or bin/vitalaize setup on Linux, typing the hub's address when it asks. A machine that was connected when you tapped Disconnect is told at once, and says the hub removed it.

Main says Unknown

The status line says why. It says "no gate run today" when the repository's gate workflow has not finished a run on main in the last day. It says "no push to main ran today" for a repository with no gate workflow: nothing a push to main started has finished in the last day. If a repository's gate file has another name than the first repository's, give it its own. See Settings.

The New Relic tab is empty

The checks it shows are set in settings.exs only (new_relic.checks); the app and vitalaize setup cannot set them yet. The key must be typed in (the VitalAIze app or vitalaize setup), or be in 1Password with the op command signed in on the board's machine. The tab says which read failed. See Settings.

Costs look wrong

Costs use the API list prices in usage.prices, not what your plan charges. A new model shows $0.00 until it has a price there; see Settings.

Too many GitHub calls

With more than about six busy repositories, the board can run out of GitHub's 5,000 calls an hour, and its GitHub panels go stale. Follow fewer. See How it works.