Browser tool doesn't support file:// URLs

Support Bug Reports
1

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

Try to have Cursor open a local index file in the built-in or remote controlled Chrome instance and the browser_navigate tool will reject it (probably due to not starting with http/https if I had to guess.)

This is a legitimate use case for single file html development, don’t always need a running server or livereload/HMR may be injected into the bundle loaded by the html file without a running html server.

Steps to Reproduce

Create a local index file and try to open it via typical file:// protocol. The easiest way to get this value is to double click to open it in Chrome first and then copy the local url. Enable either the built-in browser or Google Chrome in the agent browser setting and then instruct the agent to load that file URL. It won’t work.

Expected Behavior

It works.

Operating System

MacOS

Current Cursor Version (Menu → About Cursor → Copy)

Version: 2.0.77
VSCode Version: 1.99.3
Commit: ba90f2f88e4911312761abab9492c42442117cf0
Date: 2025-11-13T23:10:43.113Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 25.1.0

For AI issues: which model did you use?

Auto

For AI issues: add Request ID with privacy disabled

662196a9-1c78-4bc0-b100-1e1ed657ced9

Does this stop you from using Cursor

No - Cursor works, but with this issue

2

Hey, thanks for the report, I’ll pass it to the team.

6

Wish you’d fix this and it’s in Windows just as well. Browsers have been running local files forever, so it’s quite unusual.
An interim fix is to use Python’s built-in http.server (thanks to this “how to” discussion), by running:

python3 -m http.server

Or in Windows:

python.exe -m http.server

This will serve http://127.0.0.1:8080, and you’ll be able to open any local file using http://127.0.0.1:8080/[local_path] by just modifying [local_path].

7

+1
Please fix this. We shouldn’t have to launch a server to view an html file. it’s an essential browser function.

8

+1. This is really silly. Especially since it appears that it simply always adds “https://” to the URL and that’s why it fails.

image
image508×172 8.7 KB

9

Please fix! :slight_smile:

10

Hey, thanks everyone for the extra info. This is a known issue, and the team is working on a fix.

Workaround: use a local HTTP server to access HTML files. Run this in your terminal:

python3 -m http.server

After that, your files will be available at http://127.0.0.1:8000/[file_path], and the browser can open them.

More details in this thread.

11

Actually, more details are in the thread right here a few messages back. I gave there instructions for Windows too.

13

This seems to be fixed! Just right click the HTML file and choose Open in Browser.
Please mark this as Solved.

If you like a live preview rather having to click refresh after every change, there’s a free Microsoft Live Preview extension that already employs a local server. It adds a right click option called “Show Preview” and auto splits it (i.e. preview runs to the right of its source file).

image
image427×194 9.08 KB

image
image298×212 2.95 KB

15

Thanks for the update and the tip about Live Preview. It’s a helpful workaround for users who need auto refresh.

Quick clarification: native file:// support in the agent browser tool wasn’t added. What works via right click Open in Browser and Show Preview opens the file in the system or built-in browser separately from the agent browser tool, which covers the main use case for most users.

I’ll mark this as resolved since the workaround works for you. If it’s important that the agent itself can navigate file:// URLs, please start a new thread with a specific scenario.