Troubleshooting
Blender won’t connect
When 3D-Agent isn’t connected to Blender, a banner above the chat box says why. Find its text below.
Try these first
- Wait a minute or two. The first connection takes a while.
- Quit Blender and 3D-Agent. Open 3D-Agent, then Blender.
- In Blender, go to Edit → Preferences → Get Extensions and check that 3D Agent is enabled.
- Disable any other Blender MCP add-on. It can conflict.
- If you have several Blender versions, keep only one, or set yours in Settings → General → Blender path.
- Update 3D-Agent, then restart your computer.
Looking for where Blender is installed…
3D-Agent didn’t find Blender in the usual folders. Click Choose Blender… and pick your Blender app, or set it in Settings → General → Blender path. See Use a Blender in another folder.
Waiting for Blender to open…
Blender isn’t running. Click Open Blender, or open Blender 4.2 or later yourself. 3D-Agent connects automatically.
Looking for Blender 4.x…
The open Blender isn’t the version 3D-Agent set up. Either:
- Click Open Blender to open the version it names, or
- In the open Blender, go to Edit → Preferences → Get Extensions, enable 3D Agent and restart Blender.
Searching for a connection with Blender…
The extension is installed but isn’t listening yet. Click Restart Blender. 3D-Agent saves your scene when it can, then reopens Blender.
If it can’t save first, it asks Restart Blender now? Save your work in Blender before you click Restart Blender, or you lose unsaved changes.
Blender is busy with your last request…
Blender is still working. Complex scenes take a while. Nothing is lost, and the next request starts when this one finishes. Don’t restart Blender.
Waiting for a supported Blender…
Your Blender is older than 4.2. Click Download the latest Blender, install and open it, then send your prompt again.
Trying to reach Blender…
Another app is using port 9875, which 3D-Agent needs. The banner names the app. Quit it or restart your computer, then restart Blender.
Reconnecting to the 3D Agent extension…
The extension in Blender doesn’t match your version of 3D-Agent. Close and reopen Blender. If the message stays, update 3D-Agent and restart Blender.
Waiting for Blender to reload the extension…
3D-Agent just updated. Click Restart Blender to load the new extension.
Other problems
| Problem | Fix |
|---|---|
| You use the Microsoft Store version of Blender | It isn’t supported. Install Blender from blender.org or Steam, open it, and choose it in 3D-Agent. |
| Blender extension install failed | Check that Blender is 4.2 or later, then restart 3D-Agent. If it keeps failing, get help and include the reason shown. |
| Chat and Blender stop working on macOS | Turn on Local Network for 3D-Agent. See Permissions. |
| Chat and Blender stop working on Windows | Allow 3D-Agent through Windows Defender Firewall on private networks. See Permissions. |
| 3D-Agent couldn’t restart Blender | Quit and reopen Blender yourself. |
Still stuck? Get help and include your Blender version and the banner text.