Skip to main content

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

The TypeError: ... .replace is not a function is a common error in JavaScript that occurs when you try to call the .replace() method on a value that is not a string. This error is a clear signal that the variable you are working with is not the data type you expected it to be.

This guide will explain the fundamental reason this error happens, walk you through the most common scenarios where it occurs, and show you how to write "defensive" code to prevent it.

The Core Problem: .replace() is a String Method​

The .replace() method is a function that exists exclusively on JavaScript String objects. Its purpose is to search a string for a specified value or pattern and return a new string where the matches have been replaced.

The error is the JavaScript engine telling you, "You asked me to call the .replace() function, but the variable you gave me isn't a string, so that function doesn't exist on it."

Example of problem:

// This is a number, not a string.
let notAString = 12345;

// PROBLEM: Numbers do not have a `.replace()` method.
notAString.replace('3', 'Z');

Error Output:

Uncaught TypeError: notAString.replace is not a function

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

This is the most frequent source of the error. You have a number and want to replace one of its digits, but you forget that you must first convert it to a string.

Example of problem:

let myNumber = 12345;

// PROBLEM: `myNumber` is a number. You cannot call `.replace()` on it.
if (myNumber.replace('3', 'Z')) {
  // ...
}

Solution: you must first convert the number to a string before you can use string methods on it. The String() constructor is the safest way to do this.

let myNumber = 12345;

// Correct: Convert the number to a string first.
let myString = String(myNumber);

let newString = myString.replace('3', 'Z');
console.log(newString); // Output: '12Z45'

Cause 2: The Variable is an Object, null, or undefined​

This error will also occur if your variable holds any other non-string value.

A) The Variable is an Object​

This is common when working with JSON data. You might have an object that contains a string, but you are calling .replace() on the object itself.

let data = { message: 'Hello World' };

// PROBLEM: `data` is the object, not the `message` string.
data.replace('World', 'Universe');          // This will throw the error.

// SOLUTION: Access the property that holds the string.
data.message.replace('World', 'Universe');  // This works.

B) The Variable is null or undefined​

If a function or API call fails to return a string, it might return null or undefined.

let myString = null;

// This will throw "TypeError: Cannot read properties of null (reading 'replace')"
myString.replace('a', 'b');

The Solution: How to Prevent the Error​

To write "defensive" code, you should always verify that your variable is a string before calling string-specific methods on it. The typeof operator is the perfect tool for this.

function safelyReplace(input, find, replace) {
  // Add a "guard clause" to check if the input is a string.
  if (typeof input !== 'string') {
    console.error('Error: The provided input is not a string.');
    // Return a predictable value or the original input on failure.
    return input; 
  }
  
  return input.replace(find, replace);
}

// Example Usage:
console.log(safelyReplace('Hello World', 'World', 'Universe')); // Output: "Hello Universe"
console.log(safelyReplace(12345, '3', 'Z'));                    // Output: Error: ... and 12345
console.log(safelyReplace(null, 'a', 'b'));                     // Output: Error: ... and null

Conclusion​

The TypeError: .replace is not a function is a clear indicator that you are trying to call a string method on a value of the wrong type.

To solve it, follow this diagnostic checklist:

  1. Inspect the variable: Use console.log(typeof myVar) to see what the variable's data type actually is.
  2. Correct the variable type:
    • If it's a number, convert it to a string first: String(myVar).
    • If it's an object, access the correct property that holds the string: myVar.message.
  3. Add a guard clause (if (typeof myVar === 'string')) to your functions to handle incorrect data types gracefully and prevent the error from occurring.

Table of Contents