Skip to content

Triaging Issues

Jump to bottom
Juan Cruz Viotti edited this page Jan 16, 2017 · 9 revisions

Triaging Issues

This document aims to serve as an ever-evolving list of pointers and advice on how to debug user's issues.

Drive doesn't boot

If the issue can't be identified, ask the user to upload the image file somewhere for further investigation, and save it on resin.io's Google Drive, so we ensure we don't lose access to it.

These require special treatment that we don't do at the moment. See https://github.com/resin-io/etcher/issues/210

  • Check if the image includes a partition table

Some images don't include a partition table. We've seen this on some VMWare images. See https://github.com/resin-io/etcher/issues/553

  • Was the image downloaded completely?

Maybe calculate a checksum of the local file and compare it with one provided by the publisher?

Uncaught errors during writing/validation

If the issue can't be identified, or it can be consistently reproduced with a certain image, ask the user to upload the file somewhere for further investigation, and save it on resin.io's Google Drive, so we ensure we don't lose access to it.

  • Make sure the user provides a screenshot of the uncaught error along with the full stack trace

  • Narrow the issue by identifying at which point the usually happens (e.g: at the beginning of the write process, right after clicking "Flash", during the end of the validation phase)

    • If the issue happens right after clicking flash, after the elevation dialog was shown:
      • If on GNU/Linux or OS X, the error might reside on the initial unmounting routine
        • Ask the user to manually unmount the drive first to confirm. The issue might be reproducible outside Etcher, otherwise, it might indeed be an unmounting issue in our application
      • If on Windows, the error might reside on the routine that cleans up the drive (wipes its partition table)
        • Ask the user to try to wipe it out manually (see the clean command of diskpart.exe)
      • It can be an error when spawning the writer process
        • We display the command the exact command that we run in DevTools. Check that the command has no obvious issues (e.g: quoting, special characters). If its not the case, ask the user to open a terminal emulator with administrator/sudo permissions and run the command manually, to see if that shows any other information. Since the child process communicates with an IPC server, ask the user to run the command without closing the main Etcher window, otherwise the IPC server will be closed
Clone this wiki locally