This is a term meaning unexpected side effect, behavior, consequence, requirement, etc.
You frequently run into these in the worst possible moment.
For example, a Tcl gotcha is the (at least pre-8.5) Tcl treatment of numbers with leading 0. While there is a perfectly understandable reason for 010 meaning 8, if someone was writing code expecting to generate numbers from 000 to 999, they would experience gotchas with 008 , which isn't a valid octal number...
Another Tcl gotcha is to hand arbitrary strings, read from the user or a file/command, directly into a list operation without first ensuring that the contents is, in actuality, a list.
I don't intend the above as a complaint about Tcl. I intend it as an example of a gotcha (at least to someone brand new to Tcl... once you hit that one, you generally become paranoid about it...)
RS One possible gotcha is switch -- always use "--" before the switch variable, since if the value of the switch variable starts with "-", you'll get a syntax error.
KPV Also, comments w/i switch, while possible, are tricky.
RS 2010-05-10 A similar gotcha is in the text search subcommand - although the misunderstanding could be avoided by counting non-optional arguments from the end,
set whatever -this $t search $whatever 1.0
raises an error that "-this" is an undefined switch. For robustness, use
$t search -- $whatever 1.0
if the slightest possibility exists that $whatever might start with a dash.
RS 2010-02-24: Yet another gotcha we ran into last night: Consider a function
proc f x { if {$x == "00000000"} { puts "$x is NULL" } }
which reported
0E123456 is NULL
How so? Bug? No -- feature. With the == comparison operator, the operands are tried to match as integers, floats, or then as strings. And the $x in this case, though meant as a pointer in hex, could be parsed as float - with the numeric value of 0, which is numerically equivalent to 00000000. The solution of course was to use the eq operator instead.
Twylite 2012-12-12: Setting a variable in a namespace eval can clobber a global variable. See Dangers of creative writing.
set foo 10 namespace eval bar { set foo 20 ; set bar 30 } puts $foo ;# puts: 20 puts $bar ;# error: can't read "bar": no such variable