Adding "Please use -Dblabla" to fix this, will help people and bad guys would find that option anyway. Security by obscurity has never worked.
OK, assume this isn't a hacker and it is an innocent mistaken (perhaps you didn't know an agent with the same name is already registered somewhere). Will using -Drhq.agent.security-token always be the proper thing to do here?
For what YOU are probably doing right now, it probably makes sense (you already registered your agent before, but you probably --fullcleanconfig when you restarted your agent during development) - so using that -D to get your security token again will be what you want.
But in production, that may not be what the person should do. An agent is already registered with the given name in this case - what if they may be trying to start another agent, perhaps on another machine, and either "mistakenly" or "on purpose" attempted to re-use an already used agent name. In this case, we don't WANT them to use -D to use that already existing agent's token! That would be very bad - it would mean the production user now has two agents running (or at least attempting to run) with the same security token. Now, if they are on different machines, it will still fail with a different error, but the point being, if we told them to use -D, it STILL wouldn't work and they'd now be doubly confused ("but I did what the error message told me to do!").
This is one of those cases where we can "dumb down" the error message enough to make it clear to the user what to do but it may still not be the correct thing to tell them because we don't know exactly what they are trying to do. I understand we are trying to spit out error messages that make it so understandable that the user should be able to move forward without referring to the docs, but at some point we have to expect the user to know SOMETHING about how to ask their admin or read the docs.
And when I say user, I mean a "production user" - clearly, if you are a developer running into this, we can probably guess what they are doing - but I tend to write my error messages from the perspective of assuming a PRODUCTION/non-developer user is reading them.
That said, I leave it up to the UXD gurus to tell me I'm wrong and to fix it (it wouldn't be the first time I get this whole "user experience" thing ass-backwards :-)
Heiko - I would write up a BZ on this.