Skip to main content

How to Resolve "TypeError: .toLowerCase is not a function" Error in JavaScript

The TypeError: x.toLowerCase is not a function is a common error that occurs when you try to call the String.prototype.toLowerCase() method on a value that is not a string. This typically happens when you mistakenly assume a variable holds a string, but it actually holds a number, an object, null, or undefined.

This guide will explain the common scenarios that cause this error and show you the correct, modern solutions for both guarding against the error and correctly converting your data to lowercase.

The Core Problem: .toLowerCase() is a String-Only Method​

The .toLowerCase() method is a function that exists exclusively on the String.prototype. It is designed to return a new string with all of its characters converted to lowercase. It does not exist on any other data type. When you try to call it on a number, an array, a plain object, null, or undefined, JavaScript throws a TypeError.

Example of problem:

// Problem: `myData` is a number, not a string.
let myData = 123;

// ⛔️ TypeError: myData.toLowerCase is not a function
let result = myData.toLowerCase();
note

The key to solving this error is to ensure you are only calling .toLowerCase() on a true string.

Cause 1 (Most Common): The Variable is a Number​

This is a very frequent source of the error, as numbers and strings can sometimes be used interchangeably until a string-specific method is called.

Example of problem:

// Problem: `userId` is a number, not a string.
let userId = 12345;

// ⛔️ TypeError: userId.toLowerCase is not a function
let result = userId.toLowerCase();

Solution: you must first convert the number to a string before you can call a string method on it. The String() constructor or the .toString() method are the simplest ways to do this.

let userId = 12345;

// ✅ Correct: First, convert the number to a string.
let userIdString = String(userId);

let result = userIdString.toLowerCase();
console.log(result); // # Output: 12345

Cause 2: The Variable is an Object or another Non-String Type​

You might have an object and try to call .toLowerCase() on it directly, when your intent was to convert one of its properties.

Example of problem:

// Problem: `user` is an object.
let user = { name: 'Alice', email: 'ALICE@EXAMPLE.COM' };

// ⛔️ TypeError: user.toLowerCase is not a function
user.toLowerCase();

Solution: you must access the specific string property on the object that you intend to convert.

// ✅ Correct: Call `toLowerCase` on the string property.
let user = { name: 'Alice', email: 'ALICE@EXAMPLE.COM' };
let lowercasedEmail = user.email.toLowerCase();

console.log(lowercasedEmail); // # Output: alice@example.com

Cause 3: The Variable is undefined or null​

If a variable has not been initialized or a function did not return a value, it may be undefined.

Exmaple of problem:

let myData; // `myData` is `undefined`

// ⛔️ TypeError: Cannot read properties of undefined (reading 'toLowerCase')
myData.toLowerCase();

Solution: guard your code to ensure you only call toLowerCase on a valid string. Optional chaining (?.) is a modern and concise way to do this.

let myData; // `myData` is `undefined`

// ✅ Safe: If `myData` is null or undefined, the expression returns `undefined`.
let result = myData?.toLowerCase();

console.log(result); // # Output: undefined (no error thrown)

You can combine this with the nullish coalescing operator (??) to provide a default value.

// If the result is `undefined` (because the variable was nullish), fall back to an empty string.
let safeResult = myData?.toLowerCase() ?? '';
console.log(safeResult); // # Output: ""

Practical Example: A Robust safeToLowerCase Function​

This function demonstrates how to safely convert a value to lowercase, handling different data types gracefully.

function safeToLowerCase(data) {
  // Guard against null and undefined, return a default empty string.
  if (data == null) {
    return '';
  }
  
  // Convert numbers or other primitives to strings before lowercasing.
  let stringToProcess = String(data);
  
  return stringToProcess.toLowerCase();
}

// Example Usage:
console.log(safeToLowerCase('HELLO'));   // # Output: "hello"
console.log(safeToLowerCase(12345));     // # Output: "12345"
console.log(safeToLowerCase(null));      // # Output: ""
console.log(safeToLowerCase({}));        // # Output: "[object object]"

Conclusion​

The TypeError: .toLowerCase is not a function is a clear signal that you are trying to use a string method on the wrong data type.

  • Remember that .toLowerCase() is only available for strings.
  • If you have a number, you must convert it to a string first: String(myNum).toLowerCase().
  • If you have an object, you must access one of its properties that is a string: myObj.myProp.toLowerCase().
  • Use optional chaining (?.) to prevent errors when a variable might be null or undefined.

Table of Contents