Symptoms
- Deploy button shows Failed (red)
- Deploy status stuck on Uploading or Received
- Error message in the deploy status panel
Common Causes and Fixes
1. Device Offline
The Pi must be online to receive deploy commands.
Check: Device health status in the dashboard.
Fix: Resolve connectivity issues first. See Device Offline. The deploy command will be queued in RTDB and execute when the Pi reconnects.
2. Deploy Timeout
The Pi received the command but did not respond in time.
Check: The deploy status shows "Received" but never progresses to "Installing".
Possible causes:
- Node-RED is unresponsive on the Pi
- The flow is very large and takes longer to load
- Network latency between Pi and Firebase
Fix:
- Wait 30-60 seconds and check the status again
- SSH into the Pi and restart Node-RED:
sudo systemctl restart nodered - Try deploying again
3. Invalid Flow Configuration
The generated Node-RED flow has errors.
Check: The deploy error message mentions specific node errors or missing configurations.
Common issues:
- A part is missing required configuration (GPIO pin, I2C address)
- Incompatible wiring between nodes (mismatched signal types)
- Duplicate sensor IDs in the same room
Fix: Return to the Configurator, review the flagged parts, and correct the configuration.
4. Node-RED Version Mismatch
The flow uses features not supported by the Pi's Node-RED version.
Check: Compare the required Node-RED version with the installed version on the Pi.
Fix: Run an OTA update to bring the Pi agent to the latest version.
5. Disk Space Full
The Pi's SD card is full and cannot write the new flow.
Check: Device health shows disk usage above 90%.
Fix: SSH into the Pi and free up space:
sudo apt autoremove
sudo journalctl --vacuum-size=100M6. Flow Too Large
Very complex configurations with many rooms and parts can generate large flow JSON.
Fix: Consider splitting across multiple devices or reducing the number of parts.
Deploy Recovery
If a deploy fails and leaves the Pi in a bad state:
- Rollback — Open Configurator > History and restore the last working snapshot
- Manual restart — SSH and restart Node-RED:
sudo systemctl restart nodered - Fresh deploy — Make any change in the Configurator and deploy again to force a full replacement
Viewing Deploy History
All deployments (successful and failed) are logged in Configurator > History. Each entry shows:
- Timestamp
- Status (success/failure)
- Flow snapshot for rollback
- Diff against previous version
Next Steps
- OTA Update Issues for agent update problems
- Common Errors for other error messages