# Proposal for error handling

David Malcolm

The three parts of good error reporting (according to a talk by a Sun representative at the 2001 GUADEC, IIRC) are:

1. say what hasn't worked

2. say why it failed

3. make suggestions on how to fix it

I propose that the HIG should make various recommendations on how the standard menu items for working with documents should deal with errors, and that we provide a lib for making this easy for app developers (with i18n done once for the lib, covering all apps).

## Notes

The titles I've given aren't user-visible; they are for discussion of the error. The user-visible title is the "What failed:" string.

There are various places where I've avoided jargon e.g. I've spoken about "applications" and "system tasks" rather than programs; I've referred to paths as "locations"; this wording could change, I suspect there is terminology that I'm meant to use

I've chosen wording so that if something has failed due to a "permanent" cause, the message says "foo cannot do bar", whereas if the problem is more transient (e.g. is potentially fixable) the message says "foo could not do bar".

I've deliberately divided URIs into a path and file componenent; I believe this is more readable for users.

Do we want to support a convenience button for accessing files as superuser when certain permission errors occur? (with an authentication dialog?)

## File->Open

Errors that can occur:

### Path not found

Use this in preference to a mere "file not found".

What failed:

  app-name cannot find path.

Why it failed:

  writeme

Suggestions:

  - Check that you spelt the location correctly. Remember that capitalisation is significant ("MyLocation" is not the same as "MYLOCATION" or "mylocation").

  - Use the GNOME Search Tool to find your file (really?)

### File not found

What failed:

  app-name cannot find filename at path.

Why it failed:

  writeme

Suggestions:

  1. Check that you spelt the file's name correctly. Remember that capitalisation is significant ("MyFile" is not the same as "MYFILE" or "myfile").

  2. Use the GNOME Search Tool to find your file (really?)

### No read permission (path)

Use in preference to "No read permission (file)".

What failed:

  app-name cannot read filename from path.

Why it failed:

  You do not have permission to read files from that location.

Suggestions:

  Try getting your system administrator to give you permission.

### No read permission (file)

What failed:

  app-name cannot read filename from path.

Why it failed:

  You do not have permission to read that file.

Suggestions:

  Try getting your system administrator to give you permission.

### Corrupt file

What failed:

  app-name cannot read filename from path.

Why it failed:

  The file seems to be corrupt.

Suggestions:

  Try looking for a backup copy of the file (more description needed... is there a standard we should be pushing for e.g. trailing tildes?)

Convenience button:

  Open backup (only sensitive if one exists)

### Wrong version of file format

What failed:

  app-name cannot read filename from path.

Why it failed:

  Various messages are possible, depending on whether the app can recognise the file format...

  app-name does not understand the file format of filename (jargon?)

Suggestions:

  Try upgrading to the latest version of app-name, or using a different application to open the file.

### Too early version of file format

What failed:

  app-name cannot write filename to path.

Why it failed:

  writeme

Suggestions:

  writeme

### Too late version of file format

What failed:

  app-name cannot write filename to path.

Why it failed:

  writeme

Suggestions:

  writeme

## File->Save

Errors that can occur:

### Read-only volume

Use this in preference to "no permission" for things like CD-ROMS.

What failed:

  app-name cannot write filename to path.

Why it failed:

  The location you specified is a read-only device. (better wording? avoid jargon? may want to split the error into those which are genuinely read-only devices like CD-ROMS, and those which are GnomeVFS methods for which writing isn't yet implemented)

Suggestions:

  Try saving the file to a different location.

### No write permission (path)

Use this in preference to "No write permission (file)".

What failed:

  app-name cannot write filename to path.

Why it failed:

  You do not have permission to write to path.

Suggestions:

  Try saving the file to a different location, or getting your system administrator to give you permission.

### No write permission (file)

What failed:

  app-name cannot write filename to path.

Why it failed:

  You do not have permission to write to that location.

Suggestions:

  Try saving the file to a different location, or getting your system administrator to give you permission.

### Couldn't open the file (someone else has it open?)

Use this when the file is held open by another process.

What failed:

  app-name could not write filename to path.

Why it failed:

  The file may be being accessed by another application or by a system task.

Suggestions:

  Wait a few seconds and then try again. If that fails, try closing other applications using this file, or try saving to another location.

Convenience button:

  Retry

### Not enough space (permanent)

Use this when the file is too big to fit on the device, and is indeed larger than the storage capacity of the device e.g. trying to save a 1GB file on a 1.44MB floppy.

What failed:

  app-name cannot not write filename to path.

Why it failed:

  The file is too big to fit on the device. (jargon?)

Suggestions:

  The size of the file is size, but the device only has a capacity of size. Try saving the file to a different location.

### Not enough space (fixable)

Use this when the file is too big to fit on the device, but is not larger than the storage capacity of the device e.g. trying to save a 300KB file on a 1.44MB floppy which only has 100KB of free space.

What failed:

  app-name could not write filename to path.

Why it failed:

  There isn't enough space on the device. (jargon?)

Suggestions:

  The size of the file is size, but you only have size free on that device. Try saving the file to a different location, or making more space by moving unwanted files from that device to the trash. (jargon?)

### Error writing file

Use this when a general error occurs when writing the file. What to do if the file is now likely to be corrupt?

What failed:

  app-name had problems writing filename to path.

Why it failed:

  writeme

Suggestions:

  Try saving to another location.

## File->Save As...

I believe the errors should correspond to those from File->Save

## File->Save a Copy...

I believe the errors should correspond to those from File->Save

## File->Revert

fubar