Reporting a Software Problem

Jan 1, 2021 Ian Darwin

When reporting any software problem (to me or to anybody else), you need to include the following in in your report:

  • What you did…​

  • What you saw…​

  • What you think the problem might be…​

What you did

What version of the software are you using. Be specific:

  • If it’s a web site problem, when did it occur? What are the last few URLs you visited on the site? Does it happen repeatedly or did it just happen once?

  • If it’s a Java development problem, what IDE, what JDK, and what version of each?

  • If it’s a Java Cookbook problem, what day of what month did you you download the software? Is there a git identifier for the version number?

  • If it’s a mobile app problem: Android or iOS? Version? App version?

  • If it’s an OpenBSD problem, what version of the kernel and userland are you running: 6.X? 7.X? Stable or Current/Snapshot?

If it’s a mobile app problem

For iOS, I have no such resource yet, but one supposes it exists on the interwebs someplace.

If it’s a Java Compilation problem:

  • What file(s) you tried to compile? Did you change the source file or the Maven build file in any way?

  • Are you compiling it under Eclipse or with Maven?

  • The exact command you used to compile it, including computer output showing what your CLASSPATH is actually set to at compile time.

  • What version of the compiler? If you are using the JavaSE SDK, the exact output of "javac".

If it’s a Java runtime problem:

  • Your classpath

  • The command used to invoke it.

  • The exact output, including the stack trace. See below.

What you saw

Just saying "it won’t compile" or "it didn’t work" is not useful. And will not get a response.

In all cases, please send the exact and complete output from the browser or the compiler or the runtime.

For web site problems, copy and paste the whole error mess from the browser into your mail program; don’t just type one or two words from the screen.

On systems with command-line capabilities, you can use "redirection" to capture a log of program output. On developer-friendly systems (UNIX/Linux/Mac OS X) you can use the script(1) program to capture a log of the errors. On other systems, or if you’re using an Integrated Development Environment, you should be able to grab the textual log of results from your screen using copy and paste.

For Java programs, you should ensure that the code prints a stack trace if it catches any exceptions. See Java Cookbook Section 1.6, many code examples such as the code in Section 5.1, and Section 9.6 for capturing tracebacks from others' code.

What you think

If you have a theory, please include it (but mark it as such :-)).

If you want to send an update or bugfix to my software, please send it as a "git pull request" for the repos on, or send it as a diff(1) -u output. Thank you!


These steps will help you get a useful response. Depending on your support arrangements I will try to get back to you as soon as I can, but remember that free software that you aren’t paying support on is a second priority to work that pays the bills! If this is a consulting gig, that’s great; I live in Canada and I charge North American consulting rates.

See Also

I’m not the only one saying that you need to be specific! The following are a few somewhat-technology-specific guides, and one very general one, all worth reading: