How to fix TypeError: The URL argument must be a string or URL object in Node.js

Node.jsBEGINNERMEDIUMUpdated Dec 9, 2025· 187 views

This error occurs when the URL constructor or URL-related functions receive an argument that is not a string or URL object, such as undefined, null, a number, or other invalid types.

Quick fix

Fixes ERR_INVALID_ARG_TYPE

// Common problematic patterns
new URL(undefined);
new URL(process.env.MISSING_VAR);
new URL(someObject);
new URL(123);
  1. Identify where the invalid argument is passed
  2. Add type checking before URL construction
  3. Verify environment variables are loaded
  4. Handle URL construction with try-catch
node.js — error
// Common problematic patterns
new URL(undefined);
new URL(process.env.MISSING_VAR);
new URL(someObject);
new URL(123);
TypeError: The URL argument must be a string or URL object

What this error means

This TypeError is thrown when Node.js URL APIs (like the WHATWG URL constructor, url.parse(), or other URL-related functions) receive an argument of an incorrect type. Node.js expects either a valid string containing a URL or an existing URL object instance. The error is part of Node.js's argument validation system, which immediately throws TypeErrors when function parameters don't match expected types. This prevents potentially dangerous operations from proceeding with invalid data. The URL constructor and related APIs are strict about type checking because parsing URLs requires string operations, and passing non-string values could lead to unexpected behavior or security vulnerabilities.

Typical symptoms

  • Application crashes immediately when attempting to create or parse a URL
  • Error mentions "TypeError" with "ERR_INVALID_ARG_TYPE" code
  • Stack trace points to URL constructor or url.parse() calls
  • Environment variables or configuration values return undefined
  • Error occurs during application startup or when processing external data

Common causes

  1. Passing undefined or null to URL constructor when environment variable is not set
  2. Attempting to use a number, object, array, or function as a URL argument
  3. Missing or incorrectly loaded configuration that should contain URL strings
  4. Calling URL constructor with variable that hasn't been initialized
  5. Passing the result of a function that returns non-string values to URL APIs
  6. Using incorrect destructuring or property access that results in undefined values

How to fix "TypeError: The URL argument must be a string or URL object"

1Identify where the invalid argument is passed

Check your stack trace to find the exact line where the URL constructor or url.parse() is called. Look for patterns like:

javascript
// Common problematic patterns
new URL(undefined);
new URL(process.env.MISSING_VAR);
new URL(someObject);
new URL(123);

Add logging before the URL creation to inspect the value:

javascript
console.log('URL value:', typeof urlValue, urlValue);
new URL(urlValue);
2Add type checking before URL construction

Validate that your URL argument is a string before passing it to the URL constructor:

javascript
// Check if the value is a valid string
if (typeof urlString !== 'string' || !urlString) {
  throw new Error('Invalid URL: expected non-empty string');
}

const url = new URL(urlString);

For optional URLs, provide fallback values:

javascript
const apiUrl = process.env.API_URL || 'https://api.example.com';
const url = new URL(apiUrl);
3Verify environment variables are loaded

If you're using environment variables, ensure they're properly loaded before URL construction:

javascript
// Load environment variables
require('dotenv').config();

// Validate required URLs exist
if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL environment variable is required');
}

const dbUrl = new URL(process.env.DATABASE_URL);

For Next.js applications, check that variables are prefixed correctly:

javascript
// Client-side variables need NEXT_PUBLIC_ prefix
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
if (!apiUrl) {
  throw new Error('NEXT_PUBLIC_API_URL is not defined');
}
4Handle URL construction with try-catch

Wrap URL construction in error handling to provide better error messages:

javascript
function createURL(urlString) {
  if (typeof urlString !== 'string') {
    throw new TypeError(
      `Expected string for URL, received ${typeof urlString}`
    );
  }

  try {
    return new URL(urlString);
  } catch (error) {
    throw new Error(
      `Failed to create URL from: "${urlString}". ${error.message}`
    );
  }
}

// Usage
const url = createURL(process.env.API_URL);

For optional URLs, return null or a default:

javascript
function safeCreateURL(urlString, defaultUrl = null) {
  if (!urlString || typeof urlString !== 'string') {
    return defaultUrl;
  }

  try {
    return new URL(urlString);
  } catch {
    return defaultUrl;
  }
}
5Convert non-string values explicitly

If you need to work with URL objects or other types, convert them appropriately:

javascript
// If you have a URL object, use it directly or convert to string
const existingUrl = new URL('https://example.com');

// Use the URL object directly (no need to convert)
fetch(existingUrl);

// Or explicitly convert to string when needed
const urlString = existingUrl.toString();
const newUrl = new URL(urlString);

For numbers or other types that represent URLs:

javascript
// Convert port number to full URL string
const port = 3000;
const url = new URL(`http://localhost:${port}`);

Advanced notes

Type Validation Libraries: For larger applications, consider using runtime validation libraries like Zod or Joi to validate configuration and environment variables at startup:

javascript
import { z } from 'zod';

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  API_URL: z.string().url().optional(),
  PORT: z.string().transform(Number)
});

const env = envSchema.parse(process.env);
const dbUrl = new URL(env.DATABASE_URL);

URL vs. url.parse(): The WHATWG URL constructor (new URL()) is stricter than the legacy url.parse(). If you need more lenient parsing, url.parse() accepts non-string values but will return unexpected results. However, WHATWG URL is recommended for modern Node.js applications.

TypeScript Integration: Use TypeScript to catch type errors at compile time:

typescript
function buildApiUrl(endpoint: string): URL {
  const baseUrl: string = process.env.API_URL!;
  return new URL(endpoint, baseUrl);
}

URL Constructor with Base URLs: Remember that the URL constructor accepts a second parameter for relative URLs. Ensure both parameters are strings:

javascript
// Both arguments must be strings
new URL('/api/users', 'https://example.com'); // ✓ Valid
new URL('/api/users', undefined); // ✗ Throws error

Common Framework Patterns: In frameworks like Express or Fastify, configuration objects might require URL strings. Always validate configuration before passing to framework initialization to get clearer error messages at startup rather than during request handling.

Frequently asked questions

What does "ERR_INVALID_ARG_TYPE" mean?
parse(), or other URL-related functions) receive an argument of an incorrect type. js expects either a valid string containing a URL or an existing URL object instance. js's argument validation system, which immediately throws TypeErrors when function parameters don't match expected types.
How do I fix "ERR_INVALID_ARG_TYPE"?
This error occurs when the URL constructor or URL-related functions receive an argument that is not a string or URL object, such as undefined, null, a number, or other invalid types.
What causes "ERR_INVALID_ARG_TYPE"?
Passing undefined or null to URL constructor when environment variable is not set Attempting to use a number, object, array, or function as a URL argument Missing or incorrectly loaded configuration that should contain URL strings
Is the "ERR_INVALID_ARG_TYPE" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading