You're trying out a new cli tool that solves a common problem you keep running into. Before you can start using it, you need to know how to configure it properly. Luckily the site has a ton of example configs. You copy one of the examples into your favorite editor and change out the values.
You finally found the perfect tool to solve a problem that would have taken weeks of unplanned work if you had to it build yourself. Back at the command prompt you run the tool, and it spits out a short error message.
* ERR: unexpected argument (undefined) expected uint
That's strange. You probably mistyped something, so you go back to review the config. Nothing stands out as an issue, so you hop back over to the documentation. After a few minutes of reading and comparing the example with your config, you're stumped.
You run a search for the error in the github repo for the tool. No results in Issues. Either you can post a question in the repo's Issues, or dig through the source to see what you're doing wrong. You decide it would be quicker to peek at the source for the config loader.
Within five minutes you were able to trace the problem down to a recent commit. The change splits the host and port number out as separate required fields for the remoteHost config option. You add remotePort and try again. This time it starts up without issue. A little annoyed about the documentation being outdated, you're still grateful for the tool.
In this scenario, it took less than 15 minutes of troubleshooting to get back on track. It's not uncommon for people to spend upwards of several DAYS trying to get their configurations working. Especially for more complex systems supporting numerous configuration file formats, environment variable settings, command-line arguments, and dynamic configurations.
Application configuration should be treated the same as UI interactions. They should be validated before use, provide friendly error messages with context, and catch additional unsupported or unknown properties instead of ignoring them. In addition, a DEBUG or verbose logging option should be supported to view the final resolved configuration the app is running. There are few things more frustrating than having to recreate immutable config files in a staging environment over and over by guessing what could be wrong. Are the secrets being loaded? Is that environment variable taking precedence over the static config option? What is actually loaded?
* ERR: config 'remoteHost' failed validation - unexpected characters ":9093"
* ERR: config 'remotePort' missing required property
This would have pointed the user in the right direction.
Instead of writing your own configuration validation, stick with a well established standard such as JSON Schema. Even if your app uses YAML, it is still a superset of JSON.
Top comments (0)