Docs / Reference
Troubleshooting
Find the message you see, then follow “What to do”. Messages are grouped by topic.
How to read an error. Some messages end with extra detail in brackets, for example “The AI provider returned an error. (Invalid API key)”. The part in brackets comes from the provider or the server and is usually the most useful bit.
Messages about a problem on Shard’s side end with “Try again. If this continues, open Settings → Help to contact us.” To contact us, open Settings → Support, type a message and press Send. TODO (owner) the message says “Settings → Help”, but the tab is called “Support”. Make them match.
Setup: provider, model and key#
| Message | What to do |
|---|---|
| No model selected. Pick a model for this provider in settings. | Open Settings → AI → Models and pick one. |
| No API key set for this provider. Add one in settings. | Paste your key in Settings → AI → API Key, then click outside the box. See Providers and API keys. |
| That model isn’t supported here. Pick a different model. | The model was removed from Shard’s catalog, or doesn’t work in your region. Pick another model. |
| That model is unavailable right now. Try another or try again later. | Pick another model, or wait a bit. |
| Pick an available provider first. / No provider selected! | Pick a provider in Settings → AI → Providers. |
| Could not load models. | Shard couldn’t download the model list. Check your connection, then reopen the provider. |
| Could not load. Click to retry. | Same as above, in a dropdown. Click it to try again. |
The AI provider#
| Message | What to do |
|---|---|
| The AI provider returned an error. | Read the detail in brackets. A wrong or expired key, no credit on your provider account, or a model you don’t have access to are the usual causes. |
| The AI provider returned an empty response. | Send your message again. If it keeps happening, try another model. |
| Couldn’t reach the AI provider. Check your connection or try again shortly. | Check your internet. The provider may also be down; try again in a minute. |
| The AI took too long to respond. Try a faster model, or shorten the conversation. | One reply has about 2 minutes. Try a faster model, lower Reasoning, or type /compact. |
Signing in and your account#
| Message | What to do |
|---|---|
| No account on file for that username (or email). Press Create account to make one. | Check the spelling. If you’re new, press Create account. |
| Incorrect password. | Try again. Shard has no password reset yet. TODO (owner) add reset instructions. |
| Choose a longer, stronger password. | Use a longer password with a mix of characters. |
| That’s already your password. | Pick a different new password. |
| That username is already taken. | Pick another username. |
| Use 3–20 characters: A–Z, a–z, 0–9, or underscores. | Usernames can only use letters, numbers and underscores, 3 to 20 long. |
| Your account already has a username. | Use Change instead of Add in Settings → Account. |
| Add a username before changing it. | Use Add first. |
| That’s already your username. | Nothing to change. |
| You can change your username once every 30 days. (or: ...again in N days.) | Wait until the date shown. |
| That email is already registered. | Sign in with that email instead, or use another one. |
| Enter a valid email address. | Check the address for typos. |
| Your account already has an email. | Use Change instead of Add. |
| Add an email before changing it. | Use Add first. |
| That’s already your email. | Nothing to change. |
| Confirm your email with the link we sent, then sign in. | Open the email from Shard and click the link, then sign in again. Check your spam folder. |
| Authentication failed. | Sign in again. Read the detail in brackets. |
| Your session is invalid or expired. Please log in again. / Session expired. Please log in again. | Sign in again. Your chats and keys are kept. |
| Shard’s account service is unavailable right now. Please try again shortly. | Wait a minute and try again. You can still read your saved chats. |
| This network has reached its account limit. Sign in to an existing account instead. | Only 2 accounts can be created per network. Sign in to one you already have. |
Changing a username, email or password that’s already set asks for your current password first. After you change your password, your other sessions are signed out.
Usage limits and credits#
| Message | What to do |
|---|---|
| You’ve hit your message limit. | Wait for your daily or monthly window to reset. See Limits and quotas. |
| You’ve hit your web-browse limit. | Shard can’t do web searches until the limit resets. It can still read the official Roblox docs. |
| Too many requests. Slow down and try again shortly. | Wait a minute. |
| We couldn’t check your usage limits right now. Try again shortly. | A problem on Shard’s side. Try again. |
| There isn’t enough allowance or credit for this Shard request. Add credits or choose another model. | See Shard-hosted models and credits. |
| Log into an account to use the Shard provider. | Sign in, or use a provider with your own key. |
| This Shard model has reached its daily usage budget. Try another model or return after the daily reset. | Pick another model or wait. |
| Shard hosted models have reached their daily usage budget. Try again after the daily reset. | Use your own key or a connected account, or wait. |
| We couldn’t confirm Shard billing. Check your balance before sending another request. | Check your balance, then try again. Contact us if it keeps happening. |
| This Shard request was already accepted. It won’t be sent or billed again. | Nothing to do. You weren’t charged twice. |
Codex and Claude Code#
| Message | What to do |
|---|---|
| Codex is offline right now. Try again later. | Shard’s Codex relay is off. Use another provider for now. |
| Claude Code is offline right now. Try again later. | Shard’s Claude relay is off. Use another provider for now. |
| Paste the full token from claude setup-token, without spaces or line breaks. | Run claude setup-token again and copy the whole token in one piece. |
| Connect your Claude account in Claude Code settings. | Open Settings → AI, pick Claude Code, and connect. See Connected accounts. |
| The Claude relay is unavailable. Press Refresh to check the connection. | Press Refresh in the Claude Code panel. |
| That model or effort is unavailable. Choose another in Claude Code settings. | Your Claude plan may not include that model. Pick another model or reasoning level. |
| Your Claude account has reached a usage limit. | Wait for your Claude plan’s limit to reset. |
| This conversation exceeds the model context limit. Compact the chat before continuing. | Type /compact, or start a new chat. |
| The conversation contains invalid message or tool history. | Start a new chat. If it keeps happening, contact us. |
| Claude Code currently supports text conversations only. | Send text only. |
| The Claude worker stopped before the request completed. | Send your message again. |
| The Claude worker returned an unsupported response. | Try again. Contact us if it keeps happening. |
| This operation was already used with different data. Refresh before retrying. | Press Refresh in the Claude Code panel, then try again. |
| The previous Claude result is unavailable. It was not regenerated. | Send your message again. |
| The Claude relay is busy. Try again shortly. | Wait a minute. |
| The connected Claude account changed. Send a new message to continue. | Someone reconnected the account. Send a new message. |
| This chat already has an active Claude request. | Wait for it to finish, or press Stop. |
| Claude could not complete the request. Check your token and account limits. | Reconnect with a fresh token from claude setup-token, and check your Claude plan. |
| Claude Code requires the authenticated relay endpoint. | A problem on Shard’s side. Update Shard, then contact us if it continues. |
Codex errors come with their own text from the relay (for example about sign-in, capacity or models). Follow what they say. If you’re stuck, disconnect and connect again in Settings → AI.
Agents#
| Message | What to do |
|---|---|
| Use valid agent arguments, unique single-word names (excluding lead and all), and non-empty tasks. | Shard usually fixes this itself. If not, ask again with clearer tasks. |
| Only the lead can start, check or stop agents. | Nothing to do: agents can’t run their own teams. |
| Only agents can use team_wait. The lead can use check_agents with wait. | Nothing to do: Shard corrects itself. |
| Start agents before using the team channel. | Ask Shard to start agents first. |
| That teammate does not exist. Use a crew member’s name, lead or all. | Check the agent’s name in Chat details → Subagents. |
| This path already has an owner. | Another agent is editing it. The agents sort this out with team messages. |
See Agents.
Connection and server problems#
| Message | What to do |
|---|---|
| The request failed. Check your connection and try again. | Check your internet and try again. |
| Got an unexpected response from the server. Try again. | Try again. |
| Something went wrong on our end. | Try again. Contact us if it continues. |
| The Shard backend failed to handle that request. | Try again. Contact us if it continues. |
| This provider is temporarily down on our end. | Use another provider for now. |
| A database error occurred on our end. | Try again later. |
| We couldn’t deliver that message. | Your support message didn’t send. Try again later. |
| The request was missing required data. | Update Shard. Contact us if it continues. |
| The request used an unsupported method. | Update Shard. Contact us if it continues. |
| A request was made with no destination. | Update Shard. Contact us if it continues. |
| The request was malformed. | Update Shard. Contact us if it continues. |
| This provider isn’t wired up correctly. | Pick another provider and contact us. |
| The provider handler crashed. | Pick another provider and contact us. |
Other messages#
| Message | What to do |
|---|---|
| Stopped by user. | You pressed Stop. Send a new message to continue. |
| This response was interrupted. Send a new message to continue. | Studio closed, Shard restarted, or a playtest started while Shard was answering. |
| This conversation is unavailable. Create a new chat to send a message. | That chat couldn’t be loaded. Start a new chat. |
| Could not save your message. Your draft is retained; no request was sent. | Studio couldn’t save Shard’s plugin settings. Try again. If it keeps happening, restart Studio. |
| This chat already has an active request. | Wait for Shard to finish, or press Stop. Your new message goes into the queue instead. |
| Choose a model with more context. | The chat is too big for this model, even after compaction. Switch model or start a new chat. |
| Image attachments aren’t supported yet. | Describe the image in text instead. |
| Another Studio operation is recording changes. | Studio was busy recording another change. Ask Shard to try again. |
| Stale source revision; read the script again. | The script changed after Shard read it. Shard reads it again on its own. |
| Shard cannot edit its own plugin source. | Shard never edits itself. |
Shard looks broken#
- Windows are blank. Is a playtest running? Shard pauses during tests. If no test is running, click the Chat or Settings toolbar button. See Playtesting.
- Shard won’t start at all. Check the Output window for lines starting with
[Shard]and send them to us from Settings → Support. - Send and Stop, or the queue buttons, are missing. Update Shard. TODO (owner) this happens when the new UI parts are missing from the plugin’s Gui.