Error messages are hard to understand for newcomers

[benjamincombes]

Description

When coming from TSD to Typings, error message are not so clear, and do not help solving problems most people get.

For example, when using git, if I try to push a branch that has not upstream branch, I get this message :

To push the current branch and set the remote as upstream, use

git push --set-upstream origin mybranch

So I understand what the problem is, and I get a solution that is useful most of the times. Moreover, I understand that this is a standard error, I don't have to panic and a solution is easy to find.

From all error messages I got with typings, none of them helped me understand what the problem was or how to fix it. Moreover, the useful and explanatory part was hidden in the middle of verbose error output shown by default (like responded with 404, expected it to equal 200), and it feels like something went really wrong, while most of the case this is just a basic error that is easy to resolve.

First time I went from TSD to Typings, I dropped it after 10 minutes, as typings search never returned any results where TSD was working (I had to use ambiantflag), or returned results but refused to install found results, and errors messages didn't help.
Many people start using typings because of a deprecation message from STD, but if they get many errors and need a lot of time to figure out why just after switching to Typings, they might go back to TSD.
And when looking at reported issues, it looks like I'm not the only one (https://github.com/typings/typings/issues?utf8=%E2%9C%93&q=404), what is sad because otherwise Typings is really really great :) ! (Plus it might save you a lot of time by not having to deal with issues that are not real issues)

Here are some examples of problems I got, and where error messages confused me without helping me find a solution :

Scenario 1

Steps to Reproduce

1. Type typings install angular

Expected behavior:

Having an error message with most common solutions to this problems, or to an article describing it.
For example, Try adding --ambient flag (when coming from TSD, it's the case 99% of times), or a link to a wiki page explaining what are sources, and giving concrete examples.

Actual behavior:

I get this error message :
Unable to find "angular" ("npm") in the registry. Did you want to try searching another source? Also, if you want contribute these typings, please help us: https://github.com/typings/registry that doesn't help so much.

Moreover, I get many verbose error messages, like caused by https://api.typings.org/entries/npm/angular/versions/latest responded with 404, expected it to equal 200
that look like something went really wrong, while it is just something common.

Scenario 2

Steps to Reproduce

1. Type typings search gulp-protractor
2. As a result is found, type typings install gulp-protractor
3. Get an error :

Typings ERR! message Unable to find "gulp-protractor" ("npm") in the registry. Did you want to try searching another source? Also, if you want contribute these typings, please help us: https://github.com/typings/registry
typings ERR! caused by https://api.typings.org/entries/npm/gulp-protractor/versions/latest responded with 404, expected it to equal 200

typings ERR! cwd /Users/benjamincombes/Documents/Projects/match-connect-web
typings ERR! system Darwin 15.4.0
typings ERR! command "/usr/local/bin/node" "/usr/local/bin/typings" "install" "gulp-protractor"
typings ERR! node -v v4.4.5
typings ERR! typings -v 1.0.4

typings ERR! If you need help, you may report this error at:
typings ERR! https://github.com/typings/typings/issues

1. Search StackOverflow or Github issues to understand what is this error
2. type typings install dt~gulp-protractor
3. Get an error :

typings ERR! message Attempted to compile "gulp-protractor" as an external module, but it looks like a global module.

typings ERR! cwd /Users/benjamincombes/Documents/Projects/match-connect-web
typings ERR! system Darwin 15.4.0
typings ERR! command "/usr/local/bin/node" "/usr/local/bin/typings" "install" "dt~gulp-protractor"
typings ERR! node -v v4.4.5
typings ERR! typings -v 1.0.4

typings ERR! If you need help, you may report this error at:
typings ERR! https://github.com/typings/typings/issues

Expected behavior:

As a result was found, I don't expect to get an error at step 2.
Or if an error occurs, I would like to get advices to fix it ; instead I have to search in Issues or StackOverflow, and understanding why this error occurs is not obvious.
At step 5, I would like to get a hint, like "try using --global flag".

Actual behavior:

I get many confusing error messages, and have to spend time figuring out why (worse, I could post duplicate Error reports on Github, that will waste your time to answer).

[mcclure]

To second this, I just want to share my thoughts looking at the error from literally the first thing I tried with typings:

$ typings install jquery --save
typings ERR! message Unable to find "jquery" ("npm") in the registry.
typings ERR! message However, we found "jquery" for 1 other source: "dt"
typings ERR! message You can install these using the "source" option.
typings ERR! message We could use your help adding these typings to the registry: https://github.com/typings/registry
typings ERR! caused by https://api.typings.org/entries/npm/jquery/versions/latest responded with 404, expected it to equal 200

typings ERR! cwd C:\msys64\home\Andi\work\h\deleteme
typings ERR! system Windows_NT 10.0.10586
typings ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\Andi\\AppData\\Roaming\\npm\\node_modules\\typings\\dist\\bin.js" "install" "jquery"
typings ERR! node -v v4.4.7
typings ERR! typings -v 1.3.1

typings ERR! If you need help, you may report this error at:
typings ERR!   <https://github.com/typings/typings/issues>

Two things right off the bat: First off, this is the example invocation from the tsd 'getting started', but it does not work with typings and the error message is incomprehensible. Second off, this is the kind of message that is more useful to someone who understands the internals of typings well enough to submit a pull request, than someone who is new or simply wishes to use it.

Some things a new user might not know are:

• What is "dt"?
• Why would I care that "dt" and "npm" are different? By "why would I care" I mean: Is it safe to install from dt? I install my javascript packages from "npm"; the message therefore makes it sound like "dt" is an alternative to "npm" and if i'm using the npm version of jquery therefore maybe the "td" typings won't work.
• Why are you searching for "jquery" ("npm") in the first place? I didn't specify "npm".
• What is the "source" option? Well of course it's --source dt, right? That's how every other command line software works. But no, apparently it's... dt~ ? Prefixed to the name of the package? I've never seen such a thing, which means telling me "use the source option" does not get me any closer to installing my package.
• Overall: What are "sources"? What is the "registry"?

One thing that would help here is including a sample invocation. If tsd install dt~jquery would have worked, then your error message should include tsd install dt~jquery in it rather than vaguely alluding to a "source" argument. (Another thing that would help is just automatically installing from DefinitelyTyped if there's a package in DefinitelyTyped, instead of expecting me to do it myself!)

Finally: The message is verbose, cluttered and the fact there is too much information gets in the way of understanding. The repeated "typings ERR!" makes this VERY hard to read and the EXCLAMATION POINTS! adds a sense of panic which is unhelpful. The "caused by" is more confusing than helpful; it is absolutely ridiculous you're printing HTTP status codes in an error message. You should not expect the user of your program to know what HTTP status code 200 is. Providing the user with a space-delineated breakdown of what they just entered ("typings" "install" "jquery") is similarly much more distracting than helpful. That entire middle block starting with "cwd C:" and ending with "typings -v" should be removed; if you don't want to remove it because it's helpful in reporting errors upstream, move it AFTER the "please file an issue" block and preface it with Please include the following information in your bug report:. If you include the "caused by" line with the status codes at all, it should also be in the "include the following information:" block because this is information which is interesting to a developer of typings but not to a user.

[accessdev]

Hey there, new here , and experiencing the "However, we found "xxxx" for 1 other source: "dt"" message. yes , clearly it s hard to figure out what to do next.

typings install dt~socket.io-client --save --global solved the issue what not so easy to find.

[frostbytedata]

@accessdev Wow this saved me hours of googling. Thanks!!

[nhrones]

Several attempts to use 'Typings' in vscode Typescript projects have left me completely baffled. Nothing I've read so far has made much sense. Simply does not work! going back to DT! Try using ws.d.ts in any project using this tool. I can get CLI success using dt~ws, but Typescript can never find the d.ts file?

[unional]

@nhrones did you list typings/index.d.ts in your tsconfig.json?

[blakeembrey]

@nhrones Please provide more detail when commenting. We're all people here trying to do our best. Can you elaborate on "going back to DT!". Typings consumes DT, so that comment really doesn't make any sense. Do you mean you're going back to copying and pasting files? If all you're interested in is consuming DefinitelyTyped, I'd recommend using the preferred approach of NPM @types by TypeScript.

[Gilead]

@blakeembrey as a fairly recent Typings user the two biggest problems I have with its usability:

• I don't want to manually insert the dt prefix -- I want my definitions without weird cryptic prefixes
• I couldn't care less if it goes into the local/ or globals/ folder, much less want to put a --global flag semi-randomly on the command line to make it work

Please excuse me from writing it this way but that's probably close to how a typical user thinks: I don't care about your internals, just give me my stuff. To give you an example of my Typings session from a few minutes ago (and that was not my first time using it, the previous times I had to google for help):

>typings install hopscotch --save
typings ERR! message Unable to find "hopscotch" ("npm") in the registry.
typings ERR! message However, we found "hopscotch" for 1 other source: "dt"
typings ERR! message You can install these using the "source" option.
typings ERR! message We could use your help adding these typings to the registry: https://github.com/typings/registry
typings ERR! caused by https://api.typings.org/entries/npm/hopscotch/versions/latest responded with 404, expected it to equal 200
typings ERR!
typings ERR! cwd C:\Users\...path...to...project...
typings ERR! system Windows_NT 10.0.10586
typings ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\username\\AppData\\Roaming\\npm\\node_modules\\typings\\dist\\bin.js" "install" "hopscotch" "--save"
typings ERR! node -v v6.2.0
typings ERR! typings -v 2.1.1
typings ERR!
typings ERR! If you need help, you may report this error at:
typings ERR!   <https://github.com/typings/typings/issues>

[ here I vaguely remember I need to put something in front of the name ]

>typings install dthopscotch --save
typings ERR! message Unable to find "dthopscotch" ("npm") in the registry.
typings ERR! message We could use your help adding these typings to the registry: https://github.com/typings/registry
typings ERR! caused by https://api.typings.org/entries/npm/dthopscotch/versions/latest responded with 404, expected it to equal 200
typings ERR!
typings ERR! cwd C:\Users\...path...to...project...
typings ERR! system Windows_NT 10.0.10586
typings ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\username\\AppData\\Roaming\\npm\\node_modules\\typings\\dist\\bin.js" "install" "dthopscotch" "--save"
typings ERR! node -v v6.2.0
typings ERR! typings -v 2.1.1
typings ERR!
typings ERR! If you need help, you may report this error at:
typings ERR!   <https://github.com/typings/typings/issues>

[ right, there was that silly tidle! ]

>typings install dt~hopscotch --save
typings ERR! message Attempted to compile "hopscotch" as an external module, but it looks like a global module. You'll need to enable the global option to continue.
typings ERR!
typings ERR! cwd C:\Users\...path...to...project...
typings ERR! system Windows_NT 10.0.10586
typings ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\username\\AppData\\Roaming\\npm\\node_modules\\typings\\dist\\bin.js" "install" "dt~hopscotch" "--save"
typings ERR! node -v v6.2.0
typings ERR! typings -v 2.1.1
typings ERR!
typings ERR! If you need help, you may report this error at:
typings ERR!   <https://github.com/typings/typings/issues>

[ I don't care about globals/local, what does it mean at all? It's irrelevant to me for sure. ]

>typings install dt~hopscotch --global --save
hopscotch

[ finally! ]

Best would be to just use dt if that's where the files are, and automatically use globals/local wherever the definition is found. If that's not possible for some reason, how about:

>typings install hopscotch --save

We found 'hopscotch' in the following locations:
* Definitely Typed globals repository; to install use: typings install dt~hopscotch --global --save
* Foo Bar local repository; to install use: typings install fb~hopscotch --save

To read about the available repositories and categories please visit http://helpful.com/helppage.html