Troubleshooting
This page lists troubleshooting paths for the AgentHub website, Desktop/Web, Hub/Edge, runtime adapters, and Feishu/Lark integration.
Docs Page Looks Like Plain Text
If /zh/docs or /en/docs appears unstyled:
- Confirm the browser is opening
https://hub.vectorcontrol.tech/zh/docs, not a localfile://path. - Open developer tools and check whether
/_next/static/...cssreturns 200. - Confirm the static server is not routing to the wrong file, such as an RSC payload or text file.
- Clear the browser cache and retry.
The docs pages are compiled from MDX to HTML, and headings, paragraphs, lists, and tables have fallback typography.
Login Has No Visible State
Check:
- whether login completed through TokenDance ID;
- whether the current page only has low-risk website personalization rather than a Hub API session;
- whether the browser blocks the required sessionStorage/cookie behavior;
- whether the Hub Server callback and relying-party configuration match.
AgentHub does not own direct GitHub, Google, or Feishu login.
Desktop Cannot Connect To Local Edge
Check:
- whether Local Edge is running;
- whether Desktop points to the correct port;
- whether another process occupies the port;
- whether the workspace is in the allowlist;
- whether Edge health checks pass.
Local execution does not require Hub login by default.
Executable diagnostics:
curl.exe http://127.0.0.1:3210/health
curl.exe http://127.0.0.1:3210/v1/health
netstat -ano | findstr :3210
Expected result: the health check returns 2xx and the port is owned by the Local Edge process. If another process owns the port, change the Edge port or stop the conflicting process, then update the Desktop Edge URL accordingly.
Known Error Codes
| Code | Common cause | First action |
|---|---|---|
runtime_unavailable | Runtime CLI missing, not logged in, or adapter preset missing | Run the matching CLI self-check in the same shell; keep provider credentials out of the browser |
workspace_outside_allowlist | Desktop/Web requested a path Edge did not authorize | Choose an allowlisted workspace or update the local Edge policy |
permission_denied | Policy denied a write, shell, network, or publish action | Inspect the approval policy and confirm whether explicit user approval is required |
approval_rejected | User rejected a pending action | Stop the run or submit a smaller task |
unauthorized_target | Hub session cannot route to the target Edge | Check project membership, device registration, and target authorization |
target_offline | Hub sees the target Edge as offline | Reconnect Desktop/Edge; inspect heartbeat and device state |
run_timeout | Task scope is too large or the runtime is blocked | Narrow the prompt, adjust timeout policy, keep the run id |
schema_validation_failed | Adapter output is not a valid AgentHub event | Fix the adapter mapping before trusting UI state |
Public issues and screenshots may include code, request id, redacted run id, runtime name, and state. Do not paste provider keys, full prompts, real local absolute paths, or private file content.
Runtime Adapter Produces No Output
Check:
- whether you are using mock, Claude Code, Codex, or OpenCode preset;
- whether the corresponding CLI is installed and works from the shell;
- whether model API keys are configured only in server/local environment variables;
- whether run events include
run.started,run.tool.call,run.failed, and related states; - whether Edge logs show permission denial, timeout, or working-directory errors.
Until the public SDK package is stable, adapter import paths in docs are architectural examples only.
Executable diagnostics:
claude --version
codex --version
opencode --version
Run only the command for the runtime you enabled. If the CLI self-check fails, fix the local installation or login first. If the CLI works but AgentHub emits no events, inspect Edge logs for runtime_unavailable, permission_denied, workspace_outside_allowlist, run_timeout, or schema_validation_failed.
OS Differences
| System | Notes |
|---|---|
| Windows | PowerShell examples use curl.exe to avoid the Invoke-WebRequest alias; use netstat -ano for port checks |
| macOS | Use curl and lsof -i :3210; confirm the CLI reads credentials from the same shell profile |
| Linux | Use curl, ss -ltnp, or lsof; if using containers or WSL, confirm loopback belongs to the same network namespace |
Local Edge, Desktop dev server, Hub Server, and Web dev server are separate processes. Do not treat UI ports such as 5173 as Edge API ports, and do not treat a Hub API session as a local Edge token.
Web Cannot See Local Files
This is expected. AgentHub Web is a Hub-only collaboration surface and must not bypass Hub to access Local Edge or local files directly. Use Desktop + Local Edge for local execution. Remote/Cloud Edge is still in development.
Feishu/Lark Does Not Respond
Check:
- whether the Feishu/Lark app is published and approved for the tenant;
- whether URL challenge, signature verification, and decryption pass;
- whether
im.message.receive_v1is subscribed; - whether the group message mentions the bot;
- whether
card.action.triggerresponds within 3 seconds; - whether slow AgentHub work is queued asynchronously;
- whether the user has completed TokenDance ID binding.
Feishu/Lark production integration is still in development. The docs describe the target boundary and implementation requirements.
Static Export Routes Return 404
Check:
- whether the site was built with
output: "export"; - whether the static host/router handles
/zh/docsand/zh/docs/...; - whether the sitemap, robots, and llms.txt include new routes;
- whether the canonical host is
https://hub.vectorcontrol.tech.
After building, check the export directory:
pnpm build
Test-Path .\out\zh\docs\index.html
Test-Path .\out\zh\docs\configuration.html
Test-Path .\out\llms.txt
For live debugging, use a cache-busting query string so the browser or CDN cannot hide an old deploy:
curl.exe -I "https://hub.vectorcontrol.tech/zh/docs?v=YYYYMMDDTHHMMSS"
curl.exe -I "https://hub.vectorcontrol.tech/zh/docs/configuration?v=YYYYMMDDTHHMMSS"