Skip to main content

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

The TypeError: ... .toLocaleDateString is not a function is a common error in JavaScript that occurs when you try to call the .toLocaleDateString() method on a value that is not a Date object. This typically happens when you are working with a variable that you think is a Date object but is actually a number (like a timestamp), a string, null, or undefined.

This guide will explain the fundamental reason this error happens, cover the most common mistake involving Date.now(), and teach you how to write defensive code to prevent this error.

The Core Problem: .toLocaleDateString() is a Date Method​

The .toLocaleDateString() method is a function that exists exclusively on instances of the Date object. Its purpose is to return a string with a language-sensitive representation of the date portion of the Date.

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

Example of problem:

// This is a string, not a Date object.
let notADate = '2023-10-27';

// PROBLEM: Strings do not have a `.toLocaleDateString()` method.
notADate.toLocaleDateString('en-US');

Error Output:

Uncaught TypeError: notADate.toLocaleDateString is not a function

Cause 1 (Most Common): Date.now() vs. new Date()​

This is the most frequent source of this error. Developers often confuse these two related but distinct Date functionalities.

  • new Date(): This is a constructor. It creates and returns a new Date object.
  • Date.now(): This is a static method. It returns a Number representing the current timestamp in milliseconds.

Example of problem:

// PROBLEM: `Date.now()` returns a number, not a Date object.
let timestampAsNumber = Date.now();

console.log(typeof timestampAsNumber); // # Output: 'number'

// This line will throw the error.
timestampAsNumber.toLocaleDateString('en-US');

Solution: if you need a Date object to work with, you must use the new Date() constructor.

// Correct: `new Date()` creates a Date object.
let dateObject = new Date();

console.log(typeof dateObject); // Output: object

// Now you can safely call `.toLocaleDateString()` on it.
let formattedDate = dateObject.toLocaleDateString('en-US');
console.log(formattedDate);     // Output: 10/28/2025

Cause 2: The Variable is Not a Date Object (e.g., a String or null)​

The error will also occur if your variable holds null, undefined, a date string, or any other type that is not a Date object.

function getDateFromAPI() {
  // Imagine this API returns a date as an ISO string
  return '2023-10-27T10:00:00.000Z';
}

let myDateString = getDateFromAPI(); // `myDateString` is now a string

// This will throw the "is not a function" error.
myDateString.toLocaleDateString('en-US');

Solution: You must first convert the string (or number timestamp) into a Date object.

let myDateString = '2025-10-27T10:00:00.000Z';

// Correct: Create a new Date object from the string first.
let myDateObject = new Date(myDateString);

let formattedDate = myDateObject.toLocaleDateString('en-US');
console.log(formattedDate); // # Output: 10/27/2025

The Solution: How to Validate Before Calling .toLocaleDateString()​

To prevent this error, you should write "defensive" code. Before you call .toLocaleDateString(), you must verify that your variable holds a valid Date object.

Solution: this simple and reusable function is the best practice for validating a Date object.

/**
 * Checks if the provided value is a valid Date object.
 * @param {*} value - The value to check.
 * @returns {boolean} True if the value is a valid Date.
 */
function isValidDate(value) {
  // 1. Check if it's an instance of a Date.
  // 2. Check if the date's time value is not NaN (to exclude "Invalid Date").
  return value instanceof Date && !isNaN(value.getTime());
}

By using this check, you can avoid the error:

let myDate = '2025-10-27'; // An incorrect value (a string)

if (isValidDate(myDate)) {
  console.log(myDate.toLocaleDateString('en-US'));
} else {
  console.error('The provided value is not a valid Date object.');
}

Practical Example: A Robust Date Formatting Function​

This function is designed to take any input, safely attempt to convert it to a Date object, and return a formatted string without crashing.

function formatDateSafely(input, locales = 'en-US') {
  let date = new Date(input);
  
  // Use our validation logic here!
  if (isNaN(date.getTime())) {
    return 'N/A'; // Return a fallback for invalid dates
  }
  
  return date.toLocaleDateString(locales);
}

// Example Usage:
console.log(formatDateSafely('2023-10-27'));      // # Output: '10/27/2023'
console.log(formatDateSafely(new Date()));        // # Output: (Today's date)
console.log(formatDateSafely('not a real date')); // # Output: 'N/A' (No error thrown!)
console.log(formatDateSafely(Date.now()));        // # Output: (Today's date)

Conclusion​

The TypeError: toLocaleDateString is not a function is a clear indicator that you are trying to call a Date-specific method on a value of the wrong type.

To solve it, follow this diagnostic checklist:

  1. Inspect your variable's type: Use console.log(typeof myVar). Is it a number or string?
  2. Ensure you have a Date object: If your variable is a timestamp number or a date string, you must first convert it to a Date object by passing it to the constructor: let myDate = new Date(myVar);.
  3. Validate: For robust code, always check that your variable is a valid Date object (instanceof Date && !isNaN(date.getTime())) before you try to call any Date methods on it.

Table of Contents