Why Good Error Messages Can Save Time and Effort

TL;DR

Make error messages precise enough to help users, so that they can resolve the problem, or at least enable them to provide meaningful input when talking to support.

The Context

For a project, I was working on an application that stored it’s content as text files. Git was used as a storage backend, so the application could track who made what changes when. – So far so good. Testing this application was done on a specific test environment somewhere on the net.

While testing was possible, it was inconvenient to have to also log in the the logging server so track what exactly was happening, and updating the application itself was not as easy either. Therefore, one day I started to set up the whole thing on my local machine. The setup and configuration was surprisingly easy. We had good documentation for where to put which files. This was the easy part. I could start the application & tell it Git repository contained the application content (those text files mentioned above).

The Problem

The problem occurred, when I tried to actually get the application data:

XYZ cannot access the repository!”

The application’s error message as displayed to the user

That’s not particularly helpful. On order to support failure analysis, an error message shown to a user should help identifying the problem and solving it, or to have a meaningful exchange with support.

I checked the log files and quickly found some related information:


<timestamp> INFO : <class_info_and_linenumber> - SSH folder: <absolute_path_to_ssh_folder>
<timestamp> DEBUG: <class_info_and_linenumber> - SSH identity file: <absolute_path_to_ssh_key_file>
<timestamp> ERROR: <class_info_and_linenumber> - Exception <library_name>Exception: Invalid private key: <key_identifier> requesting Git repo
<full_class_name>.<ExceptionType>: Cannot list remotes for git url <ssh_url_to_git_repository>

I found this surprising, since I was using the exact same identity files to access the very same Git repository from my IDE & other Git clients on my machine. Had something corrupted my key? If so, what was it?

I started by increasing the logging of the SSH library I’m using, to make sure I was using the exact same key pair in all situations. A good while later, after googling for the error message, talking to developers, and reading some documentation, I found out this: The library being used wasn’t coping well with the encryption algorithm I used when generating my public & private key pair.

While I used ‘ed25519‘, a (relatively) recent algorithm (at the time of writing this), the library (in the version that was used in the application) expected the key to be generated using ‘RSA‘. Some details are also in the post ‘“Invalid privatekey” when using JSch‘ on stackoverflow. The problem is the misleading error message: The key wasn’t invalid at all, since I could access the repository using it with other programs that (apparently) used other libraries. The key type was unknown to the library. That’s similar, but different.

A Better Error Message

Had the library error message been something like Key <key_identifier> not recognised; see documentation for supported key types, identifying and solving the problem would have been much faster and less frustrating. Words matter in error messages, too.

Error Messages Should Help You Resolve the Error

I prefer error messages to be detailed enough to help me identify the real cause of the issue and ideally give a hint at what I can do.

Take widespread error messages for pass word fields for example. They may read like this:

Your password must have at least
12 characters overall
1 uppercase & 1 lowercase character
1 number
1 of these characters: # $ % & – ? = / . , ;

A contrived error message, that’s entirely likely

Yes, there’s a lot to be said about the value and limitations of requirements like these, but at least the message helps a user to set a password that complies with the mentioned rules.

A good error message can help users to identify a problem and probably resolve it as well. They don’t have to contact your support team. Your support team doesn’t have to go though the process of identifying the same problem(s) over and over. This saves time (and probably money) on both sides, yours and the user’s.

Conveniently start a JavaScript shell (jsc) on macOS

For one of my projects I wanted an easy way to try JavaScript on a command line (similar to pry or irb in Ruby). Here’s how I found out where the program is located and how to set up my Mac to conveniently start it.

1. Find out where jsc is located on the machine:

$ find / -name jsc -type f 2>/dev/null
/System/iOSSupport/…/JavaScriptCore.framework/Versions/A/Helpers/jsc
/System/…/JavaScriptCore.framework/Versions/A/Helpers/jsc
/System/Volumes/Data/…/JavaScriptCore.framework/Versions/A/Helpers/jsc
/System/Volumes/Data/…/JavaScriptCore.framework/Versions/A/Helpers/jsc    

Searching from the root folder may be a bit excessive, though. You may consider a more limited search.

2. Look into the ‘system frameworks’ for versions

The path /System/Library/Frameworks/… was where I went to look what else is inside:

$ ll /System/Library/Frameworks/JavaScriptCore.framework/Versions
total 0
drwxr-xr-x  4 root  wheel  128 Jan  1  2020 .
drwxr-xr-x  4 root  wheel  128 Jan  1  2020 ..
drwxr-xr-x  5 root  wheel  160 Jan  1  2020 A
lrwxr-xr-x  1 root  wheel    1 Jan  1  2020 Current -> A

Aha, there’s a link named Current that (currently) points to A. I used this link in the next step. This way I can still use the same link, even if (when!) an OS update causes the file that’s linked to changes.

3. Link to the current version

I set a link somewhere in within $PATH. I have a bin folder in my home directory, so it put the link there:

ln -s /System/Library/Frameworks/JavaScriptCore.framework/Versions/Current/Helpers/jsc ~/bin/jsc

3. Set a variable ‘console’ for output

To output things, use this to define a variable console in a running JavaScript shell.

var console = {log : debug};

While jsc provides a print function, I find it convenient to stick to the more idiomatic console.log.

4. Use ‘jsc’

$ jsc
>>> var console = {log : debug};
undefined
>>> console.log(function(){})
--> function (){}
undefined
>>> 1 + 1
2 

The Different Ways of Pry and Irb

I ran into an interesting little problem when doing sone Ruby (and Rails) work today: I wanted to try something in pry and, inside that Rails project I issued the following command:

$ pry -r sqlite3
…/gems/pry-0.14.1/lib/pry/pry_class.rb:103:in `require': cannot load such file -- sqlite3 (LoadError)
  from …/gems/pry-0.14.1/lib/pry/pry_class.rb:103:in `block in load_requires'
  from …/gems/pry-0.14.1/lib/pry/pry_class.rb:102:in `each'
  from …/gems/pry-0.14.1/lib/pry/pry_class.rb:102:in `load_requires'
  from …/gems/pry-0.14.1/lib/pry/pry_class.rb:143:in `final_session_setup'
  from …/gems/pry-0.14.1/lib/pry/cli.rb:82:in `parse_options'
  from …/gems/pry-0.14.1/bin/pry:12:in `<top (required)>'
  from …/bin/pry:23:in `load'
  from …/bin/pry:23:in `<main>'
  from …/bin/ruby_executable_hooks:22:in `eval'
  from …/bin/ruby_executable_hooks:22:in `<main>'

Interesting! I have both gems, pry and sqlite3 installed. A similar attempt using irb worked fine:

$ irb -r sqlite3
3.0.1 :001 > SQLite3::VERSION
 => "1.4.2"
3.0.1 :002 >

Maybe I confused the environment by setting some environment variable or other? With a newly opened command shell I got this:

$ pry -r sqlite3
[1] pry(main)> SQLite3::VERSION
=> "1.4.2"
[2] pry(main)>

Remarkable. In that new shell the irb command behaved the same as before.

The only difference I could find was that the original call to pry happened in a Rails project – which is using Bundler to organise the Rubygems used in the project and resolve dependencies. As a small experiment I set up a minimal project that uses bundler and a rather short Gemfile:

source "https://rubygems.org"

gem  'limit_detectors'

The gem ‘limit_detectors’ is one I wrote and I know that is doesn’t depend on other gems. Issuing the pry command again … worked? Why? Some more investigation was needed…

Finally, I realised that another gem (Guard, to be specific), uses pry. Therefore my Rails project’s development environment indirectly depends on pry. It looks like pry recognises that it’s running as part of a Bundler project, even when it is not explicitly called using bundle exec pry …, which in turn causes it (pry) to ‘only’ recognise the gems that are also installed using Bundler. – And sqlite3 isn’t in this case, since I’m using PostgreSQL throughout.

Since irb comes with the Ruby installation and is not part of the bundled gems, it ignores the bundler context when called like this:

irb -r sqlite3

However, explicitly calling it in the bundler context in a project that doesn’t depend on ‘sqlite3’ (directly or indirectly) will cause an error message:

$ bundle exec irb -r sqlite3
…/rubies/ruby-3.0.1/lib/ruby/3.0.0/irb/init.rb:376: warning: LoadError: cannot load such file -- sqlite3
3.0.1 :001 >

Nice! This is essentially the same problem, I faced at the very beginning, when pry couldn’t find the sqlite3 gem.

A Local Rails Server in a Local Network

I’m currently working on a Rails app, that I want to have available in my local network on the default port that Ruby on Rails uses: 3000.

To do that, I added a line to the development config (config/environments/development.rb):

config.hosts << 'hostname.local'

Update: Apparently adding the line config.hosts.clear works as well. Details about this are explained in the Rails Guides.

I started using Foreman to achieve this, and installed it using:

gem install foreman

Note that, according to a Wiki Page on Github, it’s not recommended to put foreman into the Gemfile.

Then I created a Procfile that Foreman uses to start the web server (which currently is the only process I need it to start):

web: bundle exec rails s -b 0.0.0.0 -p 3000

The -b 0.0.0.0 binds the process to that IP address and -p 3000 instructs it to use port 3000.

With that set up foreman start can be used to start a Rails server in development which is available in the local network.

This way I can check the layout and functionality on a mobile phone or one of my iPads.

Monitoring Tomcat

Recently, I faced an issue with an application which is deployed in a Tomcat web container: In one of the environments it started to consume a lot of CPU cycles and memory.

My first attempt to investigate, is to run things locally and have a look at the Activity Monitor that comes with macOS. Often enough it’s enough to notice which app uses a lot of memory or CPU cycles.

This time though, I wanted some deeper insight and I already knew what I was looking for. Some searching in the net brought up Glowroot.

Even though I’m not experienced in using Tomcat, it was pleasantly easy and quick to get going:

  • Download a zip file and unpack it.
  • Copy the folder to a place where it’s convenient. I copied it into an existing folder I’m using to keep configuration info for Tomcat anyway.
  • Set up a way for Tomcat to find and use the Glowroot jar file.
  • Start Tomcat
  • Open a Browser at http://localhost:4000

The details for these steps are nicely explained on the GitHub Wiki of this project.

An example graph is this, taken from the projects demo site at https://demo.glowroot.org/

The my project this (so far) only confirmed that memory consumption can increase a lot when the system gets some traffic. Using well over 10GB of memory within a few minutes is a lot, especially when that memory isn’t released any time soon.

Are you using a tool that was particularly easy to use and provided what you were looking for? Which one?

Navigation

%d bloggers like this: