Troubleshooting

When CoreSnap is working well, the flow should feel straightforward. When it does not, this page is here to help you narrow things down quickly.

Authentication and access

What this usually looks like:

• You cannot sign in
• Your token expires unexpectedly
• You can sign in but cannot manage devices or media

What to check:

• Confirm you are using the correct environment and account
• Verify your role includes the permissions needed for the action
• Sign out and sign in again if the session appears stale

Device registration issues

What this usually looks like:

• The device does not appear after creation
• The device exists but cannot be updated or linked to the expected hardware profile

What to check:

• Make sure the selected device type matches the intended use case
• Confirm the board profile matches the physical hardware
• Review any required identifiers before saving the device record

Firmware problems

What this usually looks like:

• Firmware is uploaded but the device does not use it
• The device reports an outdated or incompatible firmware state

What to check:

• Confirm the firmware is intended for the selected board profile
• Verify you are targeting the correct device
• Recheck the device's latest firmware state before re-uploading

Browser flashing problems

What this usually looks like:

• The browser cannot connect to the board over USB
• The flasher opens, but release selections are missing
• Flashing starts and then stops or fails verification

What to check:

• Make sure your browser supports Web Serial
• Confirm the board is connected over USB and not already claimed by another tool
• Confirm you selected the correct board profile
• If app firmware options are missing, check whether your role has access to firmware releases
• Retry with the erase options only when you actually need them

Configuration problems

What this usually looks like:

• The device accepts a configuration change but behaves incorrectly
• A configuration update is rejected or appears incomplete

What to check:

• Start from the correct board profile or template
• Validate all required fields before submitting
• Compare the intended change with the last known working version

Sound and playlist sync issues

What this usually looks like:

• Sounds are missing on the device
• A playlist exists in the platform but cannot start on the device

What to check:

• Confirm the media assets were uploaded to the correct device
• Make sure the Pi Service is healthy when audio features depend on it
• Re-run the sync flow and confirm the asset names are what you expect

Animation issues

What this usually looks like:

• An animation is saved but does not run as expected
• Manifest data looks incomplete

What to check:

• Review the target device and intended motion profile
• Confirm the animation belongs to the correct device
• Keep early tests small and verify one known-good motion before expanding

When to escalate

If a device keeps failing after firmware and configuration both look correct, or if playback and connectivity are failing at the same time, the problem is probably larger than one bad content change. That is usually the right moment to escalate and inspect the environment or device itself.