Troubleshooting devices
What to check when a hydrometer or sensor doesn't send data to BrewForge, readings don't appear on the brew, or values look wrong.
Start on the device's page: Recent data lists the payloads BrewForge stored and where each one went. Click a row to see the payload exactly as it arrived and, for a Custom Stream, how each field was read.
The device stays on "Waiting for the first reading"
BrewForge hasn't received a single valid request yet.
- Check the URL. Copy it again with ⋯ → Copy webhook URL (or the copy button under Setup) and paste the complete URL, including
?key=…. A missing or wrong key is rejected. - Check the device type. A Tilt added as iSpindel (or the other way round) gets its data parsed with the wrong format. The type can't be changed; delete the device and add it again with the right type.
- Check the internet connection of the device or bridge. For a RAPT Pill, its readings must first show up in the RAPT Portal.
- Restart the device after saving its settings (iSpindel and GravityMon apply push settings after a restart).
- Wait for one interval. Many devices only send every 15 to 60 minutes. The device page updates on its own when the first reading arrives.
"No reading since …" or "things to check"
A device connected to a brew or keg that hasn't sent a reading for more than a day is flagged: its row on the Devices page says no reading since …, the page shows a things to check line, and the device page says No reading for over a day while connected to …. Usually the battery is empty, the device lost its WiFi, or it was taken out of the fermenter without being disconnected. Fix the device, or disconnect it if fermentation is over.
A device is Offline (grey dot) as soon as its last stored reading is older than 30 minutes; that alone is normal for devices with a long interval.
The device is online, but the brew gets no readings
- Connect the device to the brew. Connected to on the device page must name the brew. On a Tilt Bridge, connect the color device (for example Tilt Black), not the bridge.
- Check that the reading has a gravity. Only readings with a gravity value (or bubbles per minute) are added to a brew. A Custom Stream that maps only temperature stores readings on the device but doesn't add brew readings.
- Check the brew's status and plan. Only active brews (Brew Day, Fermenting, Conditioning) can be picked. On the free plan, brews over the 20-brew limit are locked and don't receive device readings.
Not every reading shows up
BrewForge stores at most one reading every 14 minutes per device. That is expected; see logging interval.
Values look wrong
| Symptom | Likely cause | Fix |
|---|---|---|
| Temperature is far too low (around −7 °C at room temperature) | A Tilt bridge sends °C without saying so; BrewForge reads Tilt temperatures as °F | Let the bridge send °F, or include temp_units: "C" |
| Gravity is missing although the device sends one | The value is outside 0.800–1.200 SG after conversion, for example Plato sent without a unit | Send the unit (gravity-unit: "P"), or map the unit in a Custom Stream |
| Gravity is off by the same amount all the time | Calibration | Set a gravity offset |
| Gravity is off by different amounts at different gravities | The device's calibration curve | Recalibrate the device (iSpindel polynomial, Tilt calibration) |
| Custom Stream payloads say Nothing matched | The paths in the mapping don't match the payload | Open the payload in Recent data, compare it with How it was read, and fix the paths with Edit mapping; nested JSON needs dot paths |
Error responses
If you can see the HTTP response (Custom Stream, curl, Node-RED, Send a test payload), it tells you what went wrong:
| Status | Message | Meaning |
|---|---|---|
| 401 | Missing device credential | No key in the URL and no Authorization: Bearer header. |
| 401 | Invalid API key | The key doesn't belong to any device, for example because the device was deleted. |
| 401 | Conflicting device credentials | The URL key and the Bearer token are different. |
| 400 | Invalid payload | The body isn't valid JSON or form data. |
| 400 | Missing Tilt color in payload | A Tilt Bridge request without color. |
| 413 | Payload too large (max 64 KB) | The request body is bigger than 64 KB. |
Still stuck? Report a problem under Inbox & Tickets (section Help in the sidebar) and include the device type and what Recent data shows.