Profiles·Public

bcryptjs

semver>=2.0.0postconditions22functions9last verified2026-06-19coverage score100%

Postconditions — what we check

hash · hash-type-error
error
Whenpassword is not a string or Buffer, or salt is invalid type
ThrowsError: Illegal arguments: [actual_type], [actual_type]
Required handlingCaller MUST wrap bcrypt.hash() in try-catch block or use .catch() handler. Type errors occur when forgetting await on Promise or passing wrong types. Validate input types before calling hash() to provide better error messages.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[1]
hash · hash-invalid-salt
error
Whensalt parameter is not a string, number, or valid salt format
ThrowsError: Invalid salt version or Illegal arguments
Required handlingCaller MUST handle errors from invalid salt parameter. Use genSalt() to generate valid salts, or pass numeric salt rounds (recommended: 12).
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[2]
hash · hash-rounds-out-of-range
error
Whensalt rounds < 4 or > 31
ThrowsError: Rounds out of range (4-31)
Required handlingCaller MUST validate salt rounds are between 4 and 31. Production systems should use rounds >= 12 for adequate security.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[3]
hash · hash-internal-failure
error
Wheninternal hashing operation fails
ThrowsError
Required handlingCaller MUST handle unexpected errors from hash() operation. While rare, internal failures can occur and should not crash the application.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[4]
compare · compare-type-error
error
Whenpassword or hash parameter is not a string
ThrowsError: Illegal arguments: [actual_type], [actual_type]
Required handlingCaller MUST wrap bcrypt.compare() in try-catch or use .catch() handler. Type errors commonly occur when retrieving hash from database as Buffer instead of string, or when password input is undefined/null.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[5]
compare · compare-invalid-hash
error
Whenhash parameter is not a valid bcrypt hash format
ThrowsError: Invalid hash provided or hash is not a valid bcrypt hash
Required handlingCaller MUST handle errors from malformed hash values. Database corruption, string truncation (VARCHAR < 60), or encoding issues can cause invalid hashes. This is the #1 production authentication bug.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6]
compare · compare-internal-failure
error
Wheninternal comparison operation fails
ThrowsError
Required handlingCaller MUST handle unexpected errors from compare() operation. Errors should not be silently swallowed as they may indicate security issues or data corruption.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[4]
genSalt · gensalt-invalid-rounds
error
Whenrounds parameter < 4 or > 31
ThrowsError: Rounds out of range (4-31)
Required handlingCaller MUST wrap genSalt() in try-catch or use .catch() handler when rounds parameter could be invalid. Validate rounds before calling.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[3]
genSalt · gensalt-type-error
error
Whenrounds parameter is not a number
ThrowsError: Illegal arguments: [actual_type]
Required handlingCaller MUST validate rounds is a number. Common error when reading from environment variables or config files without parsing to integer.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[7]
genSalt · gensalt-rng-failure
error
Whenrandom number generator fails (browser context without setRandomFallback)
ThrowsError: Secure random number generator not available
Required handlingCaller MUST handle RNG failures. In browser environments, call bcrypt.setRandomFallback() to provide a CSPRNG fallback.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[8]
hashSync · hash-sync-type-error
error
Whenpassword is not a string or salt is not a string/number
ThrowsError: Illegal arguments: [typeof password], [typeof salt]
Required handlingCaller MUST wrap hashSync() in a try-catch block. Type errors throw synchronously. Most common cause: passing undefined/null password (unvalidated input) or an already-hashed password Buffer from a database query instead of a string. Unlike the async hash(), there is no .catch() available — only try-catch.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
hashSync · hash-sync-rounds-out-of-range
error
Whensalt is a number and rounds < 4 or > 31
ThrowsError: Illegal number of rounds (4-31): [N]
Required handlingCaller MUST wrap hashSync() in try-catch when rounds parameter comes from configuration or environment variables. Validate rounds is 4-31 before calling. Production minimum recommended: 12.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
hashSync · hash-sync-blocks-event-loop
error
WhenhashSync() is called in a Node.js HTTP request handler or any async context
ThrowsDoes not throw — instead blocks event loop for 100ms-400ms+
Required handlingCaller MUST NOT use hashSync() in Express/Fastify/Next.js API routes, background workers serving concurrent requests, or any code running in the main event loop. The operation blocks all other requests for its duration. Use async hash() instead. hashSync is ONLY appropriate in: CLI scripts, database seed files, one-time migration scripts, and test setup (beforeAll/beforeEach fixtures).
costhighin proddegraded serviceusers seeservice unavailablevisibilityvisible
Sources[10]
compareSync · compare-sync-type-error
error
Whenpassword or hash is not a string
ThrowsError: Illegal arguments: [typeof password], [typeof hash]
Required handlingCaller MUST wrap compareSync() in try-catch. Common cause: retrieving hash from database as Buffer instead of string, or passing undefined when the user record is not found. Unlike the async compare(), no .catch() is available.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
compareSync · compare-sync-silent-false-on-bad-hash
error
Whenhash parameter is a string but not exactly 60 characters (malformed bcrypt hash)
Returnsfalse — NOT an error, not a throw. Silent authentication failure.
Required handlingCallers who only check `if (isMatch)` without validating that the stored hash is well-formed will silently deny authentication for ALL users whose hashes were truncated, corrupted, or stored in a VARCHAR(40) column. Always validate that the hash column is VARCHAR(60) or CHAR(60) in the database schema and that the hash was not corrupted in transit. This is the #1 silent authentication bug with bcryptjs — the function returns false for wrong-password AND bad-hash, making it impossible to distinguish them without additional checks.
costhighin prodsilent failureusers seeauthentication failurevisibilitysilent
Sources[9][2]
compareSync · compare-sync-blocks-event-loop
error
WhencompareSync() is called in a Node.js HTTP request handler or async context
ThrowsDoes not throw — instead blocks event loop for 100ms-400ms+
Required handlingCaller MUST NOT use compareSync() in Express/Fastify/Next.js API routes or any code running in the main event loop. Use async compare() for all authentication endpoints. compareSync is ONLY appropriate in: CLI scripts, test setup, and one-off verification scripts.
costhighin proddegraded serviceusers seeservice unavailablevisibilityvisible
Sources[10]
genSaltSync · gensalt-sync-invalid-rounds
error
Whenrounds is not a number, or rounds < 4 or rounds > 31
ThrowsError: Illegal arguments: [typeof rounds] (wrong type) or Error: Illegal number of rounds (4-31): [N] (out of range)
Required handlingCaller MUST wrap genSaltSync() in try-catch when rounds comes from configuration or user input. Validate rounds is an integer between 4 and 31. Common error: reading BCRYPT_ROUNDS from environment variable as string without parseInt() — e.g., process.env.BCRYPT_ROUNDS returns '12' (string) not 12 (number).
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
genSaltSync · gensalt-sync-rng-failure
error
Whencalled in a browser environment without setting a random fallback via setRandomFallback()
ThrowsError: Secure random number generator not available
Required handlingIn browser environments, bcryptjs requires calling bcrypt.setRandomFallback() with a CSPRNG implementation before using any salt-generating functions. Node.js environments use crypto.randomBytes() automatically and are unaffected.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
getRounds · get-rounds-type-error
error
Whenhash parameter is not a string
ThrowsError: Illegal arguments: [typeof hash]
Required handlingCaller MUST wrap getRounds() in try-catch when the hash comes from a database column or external source where it could be null, undefined, a Buffer, or any non-string type. Common cause: the user record was not found (hash is undefined) and the calling code did not guard, so a synchronous throw bubbles up into a login or password-rotation handler that does not expect it. Validate that the hash is a string of length 60 before calling getRounds().
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
getSalt · get-salt-type-error
error
Whenhash parameter is not a string
ThrowsError: Illegal arguments: [typeof hash]
Required handlingCaller MUST wrap getSalt() in try-catch when the hash comes from a database row or external source where it may be null, undefined, or a non-string type (Buffer, Object). The function throws synchronously — there is no Promise and no .catch() path. Validate that the hash is a 60-character string before calling.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
getSalt · get-salt-illegal-length
error
Whenhash is a string but its length is not exactly 60 characters
ThrowsError: Illegal hash length: [length] != 60
Required handlingCaller MUST handle the length-validation throw. Common cause: the hash was stored in a VARCHAR column narrower than 60 (e.g. VARCHAR(40)), or it was trimmed/encoded on insert, or it was migrated from a different bcrypt variant (some libraries produce $2y$ hashes that may have different lengths). Unlike compareSync() which silently returns false for malformed hashes, getSalt() throws explicitly — so an uncaught throw will crash the handler. Validate hash.length === 60 before calling, or wrap the call.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
truncates · truncates-type-error
error
Whenpassword parameter is not a string
ThrowsError: Illegal arguments: [typeof password]
Required handlingCaller MUST wrap truncates() in try-catch or validate the input is a string first. Common cause: passing undefined when the user-submitted form field is missing, or passing a Buffer from a binary upload path. The function is synchronous — there is no Promise rejection or .catch() handler available.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

Need a different package?

Request a profile