HAWKNET DOCS

Troubleshooting

Something broken? Find your symptom below and follow the fix.

Connection issues

“No daemon found” or “Waiting to reconnect”

The Studio plugin cannot find a Hawknet daemon on your machine. Two causes cover nearly all reports.

Your AI client is not running. The AI client (Claude Code, Codex, Cursor) starts the Hawknet daemon and stops it when it exits. Studio alone never starts the daemon, so with no AI client open, “No daemon found” is expected rather than an error.

Fix: Open your AI client first, then open Studio. The plugin connects within a few seconds. If Studio was already open, click Reset Hawknet in the toolbar.

Studio is blocking the plugin’s HTTP requests. The first time Hawknet runs, Studio asks whether the plugin may make HTTP requests. If that prompt was denied, Studio remembers the denial and every connection attempt fails with “No daemon found”, even after reinstalling Hawknet or restarting your PC.

Fix: In Studio, open Plugins → Manage Plugins, find Hawknet, open its permission settings, and allow HTTP requests. Then click Reset Hawknet.

“Plugin not connected”

The Hawknet daemon is not running, or the Studio plugin is not active.

Fix: Make sure Roblox Studio is open with a place file loaded and your AI client is running; the client is what starts the daemon (see “No daemon found” above). Then click Reset Hawknet in the Studio toolbar. Note that hawknet status in a terminal checks your license, not whether the daemon is running.

Plugin installed but “Reset Hawknet” not visible

Studio does not detect new plugins until it restarts.

Fix: Close Roblox Studio completely and reopen it.

“Command timed out after 30 seconds”

The plugin received the command but Studio never responded. This usually means Studio is frozen or a script is stuck in an infinite loop.

Fix: Check Studio’s Output window for Luau errors. If Studio is unresponsive, force-close it and reopen.

“Circuit breaker open”

Repeated connection failures triggered a temporary safety shutoff.

Fix: Wait 30 seconds. The plugin retries automatically. If it persists, click Reset Hawknet in the Studio toolbar.

License issues

“No valid Hawknet license”

Hawknet could not find an active entitlement for this install.

Fix: If you do not have an active subscription yet, get one from the product page. If you should already have access, treat this as a bug and email support so we can check it.

I pasted the wrong license key and now activation seems stuck

This is usually a local activation-state issue, not a permanent lockout.

Fix: First, run hawknet activate <correct-key> again with the right key. If it still fails, delete Hawknet’s local license files and retry activation:

  • Linux: ~/.hawknet/license.json, ~/.config/hawknet/license.key, ~/.config/hawknet/license_cache.json
  • macOS: ~/.hawknet/license.json, ~/Library/Application Support/hawknet/license.key, ~/Library/Application Support/hawknet/license_cache.json
  • Windows: %USERPROFILE%\\.hawknet\\license.json, %APPDATA%\\hawknet\\license.key, %APPDATA%\\hawknet\\license_cache.json

If that still does not fix it, email support and mention that activation got stuck after entering the wrong key.

Sync issues

Sync conflicts after editing the same file in both Studio and on disk

Both Studio and the filesystem changed since the last sync. Hawknet does not know which version to keep.

Fix: Ask the AI to check for conflicts and resolve them. You can choose to keep the Studio version, the filesystem version, or merge manually.

Multi-agent issues

“Blocked” or lock errors

Another AI session is editing the same script. Hawknet uses locks to prevent two agents from writing to the same thing at once.

Fix: Wait for the other session to finish. Locks expire after 5 minutes. If you need to override, ask the AI to force-acquire the lock.

MCP configuration issues

AI client does not see Hawknet after install

The AI client was not running when Hawknet was installed, or it did not pick up the config file.

Fix: Run hawknet by itself in your terminal to reconfigure all detected clients. Then fully restart your AI client.

Open Cloud issues

Open Cloud auth fails

Hawknet cannot authenticate with Roblox Open Cloud. Credentials are missing or expired.

Disclaimer: Open Cloud support is still experimental, so auth issues here may reflect unfinished behavior on our side as well as local setup problems.

Fix: Run hawknet auth to log in via OAuth. If you use API key auth instead, set the ROBLOX_CLIENT_SECRET environment variable.

Still stuck?