Troubleshooting a `sanity graphql deploy` error with a CLI upgrade/downgrade.

Based on the error you're encountering, this is almost certainly a Node.js version issue. The ReferenceError: URL is not defined error typically occurs when running Sanity CLI commands on older versions of Node.js.

The Solution

You need to upgrade to Node.js 18 or higher (preferably Node.js 20+). The URL global object wasn't available in older Node versions, which is why you're seeing this error during sanity graphql deploy.

According to Sanity's Studio v4 documentation, the current Sanity CLI requires Node.js 20+, though Node 18 should work with older versions of the CLI. The migration guide confirms this requirement was updated from Node.js 18 to Node.js 20+.

Check your Node version:

node --version

If you're below v18, upgrade Node.js and try again.

Enabling Verbose Mode

For future debugging, you can enable verbose logging in the Sanity CLI using the DEBUG environment variable:

DEBUG=sanity:* sanity graphql deploy

Or for even more detailed output:

DEBUG=* sanity graphql deploy

This will show you much more detailed stack traces and help identify where errors are originating.

Why This Happens

The error message isn't helpful because the stack trace is coming from internal code that expects the URL global to exist. Since it doesn't exist in older Node versions, you get a cryptic error rather than a clear "please upgrade Node" message. Your schema changes are likely fine—the CLI just can't process them on the older runtime.

After upgrading Node, your sanity graphql deploy command should work normally and deploy your schema updates (including that field you've been sitting on).