Troubleshooting

My device shows as Pending but I haven't approved it yet

This is expected. The device appears as Pending as soon as the client contacts Alloy. It is waiting for an admin to approve it. Open Mesh Storage → Devices, find the device under Pending approval, and click Approve.

I approved the device but it still shows as Pending

The client picks up the approval on its next sync (every 15 seconds by default). Wait a moment and refresh. The status should update automatically. If it doesn't:

• Check that the client process is still running. For a systemd user service, run systemctl --user status alloy-edge. For a system installation, run sudo systemctl status alloy-edge. For Docker, run docker ps.
• Check the client logs for connection errors
• Verify the client can reach your Alloy endpoint on port 443

My device isn't uploading files

First confirm the device is Approved and Last seen is recent. If so:

• Check that files exist in the tracked folder. From Alloy Edge 0.9.7, you set the tracked folder with alloy-edge link --track-folder <path> and change it with alloy-edge config set track-folder <path>. Restart Alloy Edge after you change it.
• Check that files match the pattern (file_pattern in edge-sync.yaml, default *.mcap,*.json,*.jsonl)
• If mcap_require_footer: true, the client won't upload a .mcap file until it has a valid MCAP footer, so in-progress recordings won't upload until the recording stops. The default is false (the age-based upload_delay fallback applies)
• Check upload_delay. The client waits this long after a file is last modified before uploading (default 30s). See the configuration reference for your client version

My device was approved but has stopped reporting

Last seen stops updating when the client can't reach Alloy, and the Activity column moves from Active to Quiet and then Stale. Common causes:

• The client process crashed or was stopped
• Network connectivity to Alloy was interrupted
• The device's API key was rolled and the client hasn't picked up the new key yet (it should do so automatically on the next successful sync)

Check the client logs and ensure it can reach port 443.

I uploaded a file from the web but I can't query it yet

After upload, files go through several states before they're queryable:

1. Queued: the file has landed in object storage and is waiting to be processed
2. Ingesting: Alloy is parsing the MCAP and building queryable tables
3. Ingested: the file is queryable in the SQL Workbench and external Iceberg clients
4. Ingest failed: something went wrong. Hover the badge for the reason

Replay and Inspect work as soon as an MCAP file is uploaded. You don't have to wait for ingest. Only SQL requires the file to be Ingested.

If a file stays in Ingesting for an unusually long time, or shows Ingest failed, hover the status badge for the error and a suggested fix.

What ports does the client need?

Outbound port 443 (HTTPS) only. No inbound ports are required. The client initiates all connections to Alloy. Alloy never connects back to the device.

How do I rotate a device's API key?

Open Mesh Storage → Devices, select the device, and click Roll key. The old key stays valid until the client syncs, receives the new key, and confirms it. Alloy then revokes the old key. No manual update is needed on the device. See API key rotation.

Diagnostics shows no data

Diagnostics reads ROS diagnostic messages from your MCAP files. It looks for a topic whose name contains diagnostics or that uses the diagnostic_msgs/msg/DiagnosticArray schema. If no data appears:

• Confirm your robot records system health data to a ROS diagnostic topic during missions
• Check that the MCAP file actually contains diagnostic messages (you can inspect it with mcap info <file>)