Golang errors and documentation

Question

Unfortunately golang error documentation in the standard library is next to non-existent. e.g. just opening a file, the return values for the error are not documented except that you can print a string. But this is not always the right way to handle it.

Is there a way to determine what the real error code might be through trial and error rather than just printing out the text? It seems silly to match the whole text for the specific error.

e.g. given I want to ultimately achieve something like this (assuming it's right)

if fd, err := io.Open("filename"); err != nil {
  if err != io.ErrFileNotFound {
    log.Fatalf("Error opening file: %s", err)
  }
}

As far as I can tell anything that implements the error interface will be able to be used as an error. But determining what the error is is what I'm struggling with. The error may be a struct that has other fields in it like a number field to tell me what type of error it is aside from the text itself. But how would I know what other data the error contains short of looking through many source files and sometimes tens of function calls.

Does this make sense?

As a more practical example. I am using a yaml library to load a config file. If the config file doesn't exist I want to carry on (it'll use defaults). But if there is a permissions error I want the error to be treated as fatal. The problem is, it's not entirely clear what the error will look like ahead of time.

Are you asking for guidance as a library author, or are you complaining about the API of the io package? If it's the former, you can export a custom error variable e.g. var TheWorldHasEnded = errors.New("The world has ended"); client code will then be able to test whether the error they got is that one: if err == foo.TheWorldHasEnded {...}. — jub0bs
– jub0bs, Commented Jun 1, 2018 at 0:06
A bit of both. I hoped I might be able to print out an error with every piece of detail. For example, you can print structures with fmt.Printf("%+v\n", structvar). But using error you can't so I have nothing to match on but the text or trace through tens of function calls looking at source code for documentation that doesn't exist in the library docs or the io package docs or anywhere. Do you get what I mean. If I could at least get at an int variable I'd have something more useful. Or if there were a big struct of error codes somewhere — hookenz
– hookenz, Commented Jun 1, 2018 at 0:08
I agree with you, the library authors could have used more specific error types, but chose not to. Additionally, there are few standardized cross package errors, and the errors in use are rarely documented unless absolutely necessary. — Sean F
– Sean F, Commented Jun 1, 2018 at 2:13
Error docs in the standard library are usually quite excellent. But there are many packages in the standard library, so it's hard to know precisely what you're talking about. In the io library, there is, IMO reasonable error documentation. — Jonathan Hall
– Jonathan Hall, Commented Jun 1, 2018 at 6:53
@Flimsy - the documentation for the errors is a little thin. If we don't know what functions return which errors, then we may end up handling errors that are never returned which is a waste of time writing. Coming from the C world I know by the man page exactly which errors each function could return. That's what's missing. IMO, the documentation could use some work. — hookenz
– hookenz, Commented Jun 4, 2018 at 22:43

score 2 · Accepted Answer · 2018-06-01 00:24:05Z

2

Use os.IsNotExist to check for file not found errors:

f, err := os.Open("filename")
if os.IsNotExist(err) {
  // handle missing file
} else if err != nil {
  // handle other errors
}

The functions os.IsExist, os.IsPermission and is.Timeout check for other common types of errors.

The os, io and other packages declare variables for specific errors.

edited Jun 1, 2018 at 0:24

answered Jun 1, 2018 at 0:09

user5728991

Sign up to request clarification or add additional context in comments.

7 Comments

hookenz Over a year ago

So basically guess. Ok.

user5728991 Over a year ago

The package documents the four functions and their purpose. The YAML scenario in the question is covered by two of the functions, os.IsNotExist and os.IsPermission.

hookenz Over a year ago

Thanks. It's really as terrible as I thought. Obviously the libraries os and io and ioutil do not return compatible errors as I tested os.IsNotExist but that fails on a file opened by a library that looks like it is using ioutil instead. Sorry I've made a mistake I'm using a toml library not yaml but never mind.

user5728991 Over a year ago

The io and ioutil packages return compatible errors. The code in the question does not reference real functions or the ioutil package. It will help of you describe the specific problem you are having (which function you are calling, what you got back, what you expected, etc.).

user5728991 Over a year ago

You can use switch:

switch err { case os.IsNotExist(err): // do something; case os.IsPermission(err): // do somethining ; case err != nil: // do something }

|

Sodimu Segun Michael · Accepted Answer · 2018-06-01 00:21:22Z

0

Always check godoc if you are not cleared about a library. .below is the godoc io URL and read more

https://godoc.org/io

answered Jun 1, 2018 at 0:21

Sodimu Segun Michael

1171 silver badge5 bronze badges

2 Comments

hookenz Over a year ago

That's the very documentation that is missing half the errors that can be returned. :(

Jonathan Hall Over a year ago

@Matt: What, specifically, is missing? "Docs are terrible" and "missing half the errors" are not specific complaints/questions.

Collectives™ on Stack Overflow

Golang errors and documentation

2 Answers 2

7 Comments

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

7 Comments

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related