If FLAC__stream_encoder_set_total_samples_estimate() is called with a total_samples value that takes up more than 36 bits (e.g. due to a wrong calculation or some other bug), libFLAC may write files which the flac command line tool will refuse to decode ("xyz.flac: ERROR: bits per sample is 32, must be 4-24").
The ultimate reason for this seems to be that the bitwriter function FLAC__bitwriter_write_raw_uint32() does not zero out unused bits in the input value, so these bits may later 'leak' into the bitstream into bits that weren't meant to be touched.
This is particularly unfortunate given that the samples value is only supposed to be a temporary estimate which will be overwritten later with the actual value if the output is seekable. When that happens, the 'leaked' bit is never touched though, so that wrong value never gets fixed up, leading to invalid/unexpected bits in the stream info header for the bits_per_sample field.
Arguably FLAC__stream_encoder_set_total_samples_estimate() should be changed to clamp or check its input if fixing up the bitwriter is not deemed necessary (or I was confused and there isn't a problem in the first place).
Version: libFLAC 1.2.1 (debian sid package, amd64)