Troubleshooting
When a Skyelight tool fails, the agent receives a message that states the reason. Find the message or symptom below.
Access and sign-in
| What you see | Cause | Fix |
|---|---|---|
| ”Your seat here is reviewer…” | Agent tools need an owner, admin or collaborator role. Reviewers can pin and reply in the app but can’t use agent tools | Ask a workspace owner or admin to change your role. See Roles and permissions |
| ”On Free, the Skyelight MCP publishes review links…” | The organization is on the Free plan, which includes list_workspaces, list_projects and publish_review_link only | The organization owner upgrades. See Plans and billing |
| ”…open threads… Reading feedback and working it with an agent is on Skyelight Pro” | On the Free plan, list_items, search_items, whats_new and get_item return how many threads are waiting, without their text | The organization owner upgrades to read the threads with an agent. The threads are in the web app on any plan |
| A workspace is listed with a reason | A reviewer role or the Free plan applies to that workspace | Read the reason in the listing. Workspaces without a refusal keep working |
401 Invalid token, or sign-in succeeds and then every call fails | The client holds an old or mismatched sign-in | Run npx @skyelight/mcp remove, then npx @skyelight/mcp init, and sign in again |
redirect_uri does not match during sign-in | The client’s config doesn’t match the sign-in details Skyelight expects | Copy the snippet from Account Settings Coding Agents exactly, or run npx @skyelight/mcp init again |
An old sk_live_… key is refused | Workspace API keys no longer work | Create a personal token under Account Settings API Keys, or use the remote server with OAuth |
| A token that worked stopped working | The token expired, or Skyelight revoked it because you no longer hold a paid seat in that organization | Create a new token. If the token was revoked, you need a paid seat again first |
| The token can’t reach another organization’s workspaces | A token belongs to the organization it was created in | Create a token in that organization, or use the remote server |
Using the tools
| What you see | Cause | Fix |
|---|---|---|
| The agent asks for a project ID | You can reach more than one project | Ask the agent to call list_projects and choose one. With the local server, add a .skyelight.json file to the repository |
| A review or decision log looks cut off | project_review and decision_log return results in pages, to stay within the result size clients accept | The result ends with the call for the next page. Ask the agent to read the next page |
list_items says it was capped | list_items reads the 2,000 most recent threads in a project | Filter by page, type, status or assignee |
429 responses | Each personal token is limited to 300 requests a minute, with bursts of up to 120. OAuth connections for one person share one limit | Wait for the number of seconds in the Retry-After header, then retry |
| No screenshot on a thread | Screenshots are off until a workspace owner or admin turns them on | See Anchoring, context and screenshots |
| ”Screenshot: expired and deleted” | The screenshot passed the workspace’s retention period | The thread, its text and its anchor remain. See retention |
| No source file on a thread | The page wasn’t built with Skyelight Build, or that build wasn’t stamped | See Skyelight Build |
| Assigning a resolved thread is refused | A resolved thread can’t be assigned | Set the thread to open, then assign it |
| A name is refused as ambiguous | More than one person matches the name | Use the person’s email or user ID, from list_members |
Publishing for review
| What you see | Cause | Fix |
|---|---|---|
| ”This is part of a larger app…” | The code passed to publish_review_link imports other files from its app, so Skyelight can’t host it alone | Deploy the app, then call publish_review_link with its url |
| ”Only an owner or admin can add a review link…” | Adding a deployed app’s address to Review Links is limited to owners and admins | Ask an owner or admin to add the address under Project settings Review Links, or to run the call |
| ”publish_review_link takes code or url, not both…” or “publish_review_link needs code… or url…” | The call passed both, or neither | Pass code for Skyelight to host, or url for an app that is already deployed |
| ”Free includes 1 hosted prototype…” | The workspace is on the Free plan and already hosts a prototype | Publish a new version of that prototype, with its prototypeId or the same name, or upgrade to Pro |
| The badge doesn’t appear on a deployed app | The script tag isn’t in the app yet, or the link has no ?skyelight=1 | Add the script tag from the result to the app’s <head> and redeploy. Open the review link the result returned |
Contact support
Email support@skyelight.ai with the client you use, the prompt or command you ran, and the exact message you saw.
Last updated on