Troubleshooting
Common issues and how to fix them.
SmartHopper doesn't appear in Grasshopper
- Rhino version — SmartHopper requires Rhino 8+. Check Help → About.
- Blocked files (Windows) — manually downloaded DLLs may be blocked: right-click each file in the components folder → Properties → Unblock.
- Gatekeeper (macOS) — run
xattr -dr com.apple.quarantineon the components folder. - Components folder — verify files landed in Grasshopper → File → Special Folders → Components Folder.
- Restart Rhino after any change.
A provider doesn't show up / is disabled
- Trust prompt declined — re-enable it under Settings → Security (trusted providers list).
- Integrity check failed — run SmartHopper → Verify Providers; a tampered/invalid provider is refused in
Strictmode (switch toSoftif you trust the file). - Just copied a new provider — use SmartHopper → Refresh Providers.
API calls fail
| Symptom | Likely cause |
|---|---|
401/auth errors | Wrong/expired API key — re-enter it in the provider tab. |
429/quota errors | No credit — check the provider's billing console. |
| Timeouts | Increase Timeout via AI Settings; check network/proxy. |
| "capability" errors | The model lacks what you need (vision, tools, image gen) — check with AIModels. |
| Payload too large | Big file/web/canvas inputs — use GhGet filters, summarize first, or pick a bigger-context model. |
Assistant isn't using tools / gives plain answers
The model doesn't support (reliable) tool calling — pick a tool-capable model in Settings → Assistant. Local models vary; check capabilities first.
Component stays orange / red with a warning bubble
Hover the bubble — it's the runtime message. Common ones: community-provider warning (expected if you use community providers), missing input, provider not configured.
Where are the logs?
Log files roll per-day in the Grasshopper profile folder and are kept per your retention setting. Enable Live output (Settings) to echo them to the Rhino command line. In debug builds, SmartHopper → Diagnostics opens the log folder directly.
Still stuck? Ask on the McNeel forum or file a GitHub issue — attach a log excerpt with secrets removed.