Local development server isn't starting

🌵 Needle Engine
1

Unity 2022.3.63f1
Needle Engine 4.6.2
Node v22.16.0

When I try to enter Play Mode or when I use the Start Server button in the Export game object (Needle Engine inspector panel), I ultimately get this error in the console:

Your local development server should be running at https://192.168.68.54:3000. Open this link in your browser.. If that’s not the case, check the console/terminal for errors. If other content is running on port 3000, you can try to stop it and restart the server.
UnityEngine.Debug:LogWarning (object)
Needle.Engine.MenuItems/d__23:MoveNext () (at ./Library/PackageCache/com.needle.engine-exporter@4.6.2/Core/Editor/Actions/MenuItems.cs:256)
System.Runtime.CompilerServices.AsyncTaskMethodBuilder1<bool>:SetResult (bool) Needle.Engine.Utils.WebHelper/<IsResponding>d__6:MoveNext () (at ./Library/PackageCache/com.needle.engine-exporter@4.6.2/Common/Runtime/Utils/WebHelper.cs:154) System.Runtime.CompilerServices.AsyncTaskMethodBuilder1:SetResult (bool)
Needle.Engine.Utils.WebHelper/d__5:MoveNext () (at ./Library/PackageCache/com.needle.engine-exporter@4.6.2/Common/Runtime/Utils/WebHelper.cs:114)
UnityEngine.UnitySynchronizationContext:ExecuteTasks () (at /Users/bokken/build/output/unity/unity/Runtime/Export/Scripting/UnitySynchronizationContext.cs:107)

The server is not running.

I can, however, open the project in a terminal window, and manually run npm start or vite --host, and the server does start.

Why won’t it work inside Unity? Not a blocker, I guess, but a little bit unsettling for it to break at the very beginning of the tutorial.

2

Hi Aaron, thanks for sharing the details. Based on your description, the error “Your local development server should be running at https://192.168.68.54:3000” indicates that Unity isn’t successfully auto-launching the development server when you enter Play Mode or click the Start Server button in the Needle Engine Export Info. Since running npm start or vite --host manually in the terminal works fine, here are a few points to check:

• Environment & PATH – When Unity tries to spawn the Node process to start your server, it may not be using the same environment as your terminal. Ensure your system’s PATH (and any Node environment variables) are configured so Unity can find and execute Node seamlessly. Sometimes launching Unity from a terminal (or ensuring its shortcuts have the right environment) helps.

• Port Conflicts or Permission Issues – Although the error message suggests stopping any other process using port 3000, double-check that nothing else is bound to that port. Also, depending on your OS, consider running Unity with administrator privileges to allow it to spawn new processes.

• Node Version Compatibility – While Node v22.16.0 should generally work, some auto-spawn features might be more reliable with an LTS release (like Node v18). You could experiment with this to see if it makes a difference.

• Certificate/Security Prompts – Since the local dev server uses HTTPS, there might be issues with self-signed certificates or security prompts that prevent the automatic server start. The FAQ in the documentation (see the SSL discussion (docs/faq.html)) explains that browsers may require manual trust of the certificate, though that mainly affects the browser, it’s worth verifying that any UI prompts aren’t blocking Unity’s process launch.

Overall, this is a known kind of hiccup early on in the tutorial. If after these checks the server still won’t auto-start from Unity, a reliable workaround is to run the server manually via npm start or vite --host until further updates or changes in your environment are made. If the problem persists, consider using the “Report a bug” option in the Needle Engine menu to provide detailed logs to the team for deeper investigation.

Hope this helps, and feel free to share further details if the issue continues. Happy developing!

1 replies left - Become PRO for more replies.
thread_gPJuSw2bfzDcB6nbOTKlO9Zb
Reply to this post directly if you need further help (bottom right button)

3

Hi,

Thanks for sharing your feedback.

Could you share a bit more info?

  • Which template did you start with? (Normally it’s the default vite template)
  • Do you get any other errors in Unity?
  • Can you check the terminal/commandline window that opens when you start the local server from Unity and check if there’s any message that contains more information or an error?

Internally we also just run npm run start from Unity as a new process so it should technically do exactly the same.

Additionally to the above it would also help if you could send a bugreport via the menu item in Needle Engine/Report a bug so we can take a look at the log files.

4

I uploaded the bug report, including answering the questions that you asked.

5

The issue is solved:
It was caused by Node 18 failing to install/update esbuild (which is pulled in as an optionalDependency by Vite)

I can, however, open the project in a terminal window, and manually run npm start or vite --host, and the server does start. - this worked because the other terminal window was using Node 22 (LTS)