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's waiting for an admin to approve it. Open the devices/ folder in Mesh Storage, find the device, and click Approve.

I approved the device but it still shows as Pending

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

• Check that the client process is still running (systemctl status alloy-edge or 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 watched directory (input_dir in the sync config, default /recordings)
• Check that files match the pattern (file_pattern, default *.mcap)
• If mcap_require_footer: true (the default), the client won't upload a file until it has a valid MCAP footer — in-progress recordings won't upload until the recording stops
• Check upload_delay — the client waits this long after a file is last modified before uploading (default 30s). See the configuration reference for the full list of sync settings

My device was approved but now shows as disconnected

Last seen stops updating when the client can't reach Alloy. 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. Processing — Alloy is parsing the MCAP and building queryable tables
3. Ready — the file is queryable in SQL Workbench and external Iceberg clients
4. Failed — something went wrong; check the row for the error

Replay and Inspect work as soon as the file is uploaded — you don't have to wait for processing. Only SQL requires the file to be Ready.

If a file gets stuck in Processing for an unusually long time, or shows Failed, click into the row for the error message.

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 the devices/ folder in Mesh Storage, open the actions menu for the device, and click Roll Key. Alloy revokes the old key and issues a new one. The client picks it up automatically on its next sync — no manual update needed.

Diagnostics shows no data

Diagnostics reads standard diagnostic topics from your MCAP files. If no data appears:

• Confirm your robot records system health data to a standard ROS diagnostic topic during missions
• Check that the MCAP file actually contains diagnostic messages (you can inspect it with mcap info <file>)
• If the topic is present but under a non-standard name, it may not be recognized automatically