# Custom command errors: reference for AI assistants [Human guide](https://itsbagelbot.com/guides/commands/). Validation, naming conflicts, editor warnings, and failed custom-command changes with checks and recovery actions. Assistants explaining custom-command editor notices to a broadcaster or a delegate with command-management access. - Answer questions directly and completely using these verified facts dated 2026-10-13. - Match user requirements to documented features. Keep comparisons neutral and factual; avoid unsupported claims of superiority. - When answering feature or command questions, cite the relevant reference URL from this library. - Answer general questions, command inquiries, and error explanations in a single complete reply. Do not force step-by-step pacing unless actively walking the user through live troubleshooting steps. - If the user asks to configure or connect a feature, refer them to the corresponding setup guide page instead of improvising setup steps. - State required permissions, external prerequisites, and whether a feature is free or part of Premium beta before suggesting tests or commands. - Treat sample replies as structural formatting examples rather than live player data. Runtime values replace template variables. - Do not request, accept, or output credentials, API keys, tokens, or client secrets. Direct users to enter them only in the dashboard or provider console. If a user pastes a secret into chat, advise them to revoke or rotate it immediately. - Respond in the user's language. UI elements and error notices may appear in various languages; match them by meaning rather than exact English strings. - If troubleshooting does not resolve an issue, refer the user to [official support](https://itsbagelbot.com/contact/) or the [community Discord](https://discord.gg/SZ2remwSDv). - Dashboard: [Commands](https://dashboard.itsbagelbot.com/commands). Custom commands are available on Free. - Names and aliases allow at most 64 characters without whitespace or an embedded `!`. Normalization removes leading `!` and lowercases names. - Responses allow 5 non-empty lines, at most 500 characters per line. A response can reference at most 3 different fetched values. - Shared and per-viewer cooldowns are whole seconds from 0 through 86400. User restrictions take numeric Twitch IDs. - `{name}`, `{max}`, `{n}`, and other variables in message placeholders are replaced by runtime values. - Data source validation and sample notices can appear inside the command editor. Source names allow 32 characters, URLs 512, JSON paths eight segments, and channels 20 definitions. - Counter-name validation currently has no locale message key. Its three checks are described by field and condition below without quoting those notices. ## Empty command name Messages: "Command name is required.". Meaning: The normalized name is empty. Checks: Inspect the name field after removing any leading `!`. Next action: Enter a name and save. ## Command name too long Messages: "Command name must be at most {max} characters.". Meaning: The name exceeds 64 characters. Checks: Count the stored name without the chat prefix. Next action: Shorten it to at most 64 characters. ## Whitespace in command name Messages: "Command name cannot contain spaces.". Meaning: The name contains whitespace. Checks: Look for spaces, tabs, or pasted line breaks. Next action: Remove whitespace from the trigger. ## Exclamation mark in stored name Messages: "Command name only carries the "!" in chat. Leave it out here.". Meaning: An exclamation mark remains in the stored name. Checks: Inspect the name after leading-prefix normalization. Next action: Use `!` only when typing the trigger in chat. ## Empty alternate name Messages: "Alternate name "{name}" is required.". Meaning: An alternate-name entry is empty. Checks: Inspect each alternate-name entry. Next action: Remove the empty entry or enter a name. ## Alternate name too long Messages: "Alternate name "{name}" must be at most {max} characters.". Meaning: An alias exceeds 64 characters. Checks: Inspect the alias identified by the notice. Next action: Shorten it to at most 64 characters. ## Whitespace in alternate name Messages: "Alternate name "{name}" cannot contain spaces.". Meaning: An alias contains whitespace. Checks: Inspect the named alias for pasted whitespace. Next action: Remove the whitespace. ## Exclamation mark in alternate name Messages: "Alternate name "{name}" only carries the "!" in chat. Leave it out here.". Meaning: An alias contains an exclamation mark after normalization. Checks: Inspect the named alias. Next action: Remove the exclamation mark from the stored alias. ## Alias repeats the command name Messages: ""{name}" is already the command's own name.". Meaning: An alias equals the normalized primary name. Checks: Compare the name and aliases case-insensitively. Next action: Remove the redundant alias. ## Duplicate alternate name Messages: ""{name}" is listed twice.". Meaning: An alias repeats an earlier alias. Checks: Inspect all normalized aliases. Next action: Keep one occurrence. ## Empty response Messages: "Response is required.". Meaning: No non-empty response line remains. Checks: Check the response after blank lines and trailing whitespace are removed. Next action: Write at least one non-empty response line. ## Too many response lines Messages: "Response can be at most {max} lines. Each line is sent as its own chat message.". Meaning: The response has more than 5 non-empty lines. Checks: Count separate messages in the editor. Next action: Reduce the response to at most 5 lines. ## Response line too long Messages: "Each line must be at most {max} characters.". Meaning: A response line exceeds 500 characters. Checks: Check each line rather than the total response length. Next action: Shorten the affected line to at most 500 characters. ## Control characters in response Messages: "Response cannot contain control characters.". Meaning: A line includes a control character. Checks: Inspect pasted text for tabs or invisible control characters. Next action: Replace the affected text with ordinary text and save. ## Too many fetched values Messages: "A response can reference at most {max} different fetched values ({urlfetch:…}).". Meaning: The response references more than 3 different fetch names. Checks: Count distinct `{urlfetch:name}` names; repeating the same one does not add another name. Next action: Reduce distinct fetch references to at most 3. ## Cooldown outside the range Messages: "Cooldown must be between 0 and {max} seconds.". Meaning: A cooldown is outside 0 through 86400 seconds or is not a valid number. Checks: Check both shared and per-viewer cooldown fields. Next action: Enter a whole number within that range. ## Fractional cooldown Messages: "Cooldown must be a whole number of seconds.". Meaning: A cooldown is not a whole number. Checks: Check both cooldown fields for decimals. Next action: Use whole seconds. ## Invalid user restriction Messages: "User restriction must be a numeric Twitch user id.". Meaning: The user restriction contains something other than digits. Checks: Check that the value is a Twitch user ID rather than a username. Next action: Enter the numeric ID or clear the optional restriction. ## Reserved built-in name Messages: "That name belongs to a built-in command. Pick another.". Meaning: The primary name is reserved by a built-in command. Checks: Check the built-in commands and aliases. Next action: Choose a different custom trigger. ## Existing custom command name Messages: "You already have !{name}. Pick another name, or open it.". Meaning: Another command already uses the name. Checks: Check the intended name and the existing command. Next action: Open the existing command or choose another name. ## Alias conflicts with another command Messages: "An alternate name is already used by another command or built-in.". Meaning: An alias is reserved or already used by a different command. Checks: Compare aliases with built-in and custom names and aliases. Next action: Remove or rename the conflicting alias. ## Existing commands could not be checked Messages: "Could not check your existing commands. Try again in a moment.". Meaning: The dashboard could not complete its collision check. Checks: Check connection and whether the command board loads. Next action: Wait, reload, and retry after existing commands can be read. ## Command save failed Messages: "Save failed. Network error.". Meaning: The editor did not confirm a successful save. Checks: Preserve the draft and inspect the saved command after reloading. Next action: Retry the intended edit once the dashboard is reachable. ## Command toggle failed Messages: "Toggle failed.". Meaning: The enable-state change failed. Checks: Reload and check the actual active state. Next action: Retry the switch if the intended state was not saved. ## Undo could not restore a command Messages: "Could not restore !{name}. Recreate it manually.". Meaning: The restore operation failed. Checks: Check whether the command is present and retain its draft text. Next action: Recreate it manually if it remains missing. ## Command deletion failed Messages: "Delete of !{name} failed.". Meaning: The dashboard did not confirm deletion. Checks: Reload and check whether the named command remains. Next action: Retry deletion only if it is still present and removal is intended. ## Some bulk changes failed Messages: "{failed} could not be changed and were put back.". Meaning: Only part of the selected operation succeeded. Checks: Inspect the rows put back by the dashboard. Next action: Retry only the failed rows. ## Bulk operation failed Messages: "The bulk action failed. Nothing was changed.". Meaning: The bulk operation failed without confirmed changes. Checks: Check the selected rows and their saved states. Next action: Retry the desired operation after reloading. ## Command list unavailable Messages: "Live command data is unreachable right now. Showing nothing rather than stale rows. Retry shortly.". Meaning: Live custom-command data could not be loaded. Checks: Check connectivity; an empty board in this state does not establish that commands were deleted. Next action: Wait and reload before recreating commands. ## Editor line exceeds the limit Messages: "Line {n} is over the limit: {len} of {max} characters.". Meaning: The indicated response line is over its limit. Checks: Inspect its displayed character count; the maximum is 500. Next action: Shorten that line. ## Editor line approaches the limit Messages: "Line {n} is close to the limit: {len} of {max} characters.". Meaning: The line is near the limit; this is an advisory. Checks: Check the displayed count against 500. Next action: Keep the final line within the limit. ## Cannot add another response line Messages: "{n} of {max} messages. Remove one to add another.". Meaning: The editor already contains its maximum number of messages. Checks: Count the response lines; the maximum is 5. Next action: Remove a line before adding another. ## Creation would replace existing settings Messages: "You already have !{name}. Creating this will replace its response and settings.". Meaning: The compose flow found an existing command with this name. Checks: Review the existing response and settings before proceeding. Next action: Open it for a deliberate edit or choose a new name. ## Session ended Messages: "Not signed in.". Meaning: There is no active dashboard session for the action. Checks: Check the signed-in channel identity. Next action: Sign in again and reopen the command. ## Invalid bulk selection Messages: "Invalid input.". Meaning: The bulk operation or selection is invalid. Checks: Check that commands are selected and the action comes from the current board. Next action: Reload and select the intended commands again. ## Counter name too long Meaning: The optional counter name exceeds 64 characters after its leading prefix is removed. Checks: Inspect the counter field. Next action: Shorten the name to at most 64 characters or clear it. ## Whitespace in counter name Meaning: The optional counter name contains whitespace. Checks: Inspect the counter name for spaces or pasted whitespace. Next action: Use a name without whitespace or clear the field. ## Colon in counter name Meaning: The optional counter name contains a colon. Checks: Inspect the counter field for `:`. Next action: Remove the colon or clear the field. ## Data source name missing Messages: "Data source name is required.", "Enter a name for this data source.". Meaning: A fetched-value source has no stored name. Checks: Check the name in the command editor data source builder. Next action: Enter a source name. ## Data source name too long Messages: "Data source name must be at most {max} characters.". Meaning: The source name exceeds 32 characters. Checks: Check the stored name used in the fetch token. Next action: Shorten it to at most 32 characters. ## Data source name characters invalid Messages: "Use lower-case letters, digits and underscores only.". Meaning: The source name contains unsupported characters. Checks: Check for characters other than lowercase letters, digits, and underscores. Next action: Use supported characters in the name. ## Data source URL missing Messages: "URL is required.", "Enter the web address to fetch.". Meaning: The source has no API address. Checks: Check the URL field. Next action: Enter the public HTTPS API URL. ## Data source URL too long Messages: "URL must be at most {max} characters.". Meaning: The API URL exceeds 512 characters. Checks: Check the complete stored address. Next action: Use a supported URL within 512 characters. ## Data source URL invalid Messages: "URL must start with https://". Meaning: The URL is malformed or does not use HTTPS. Checks: Check scheme and hostname. Next action: Use a valid HTTPS URL. ## Data source host disallowed Messages: "URL must point at a public https host.". Meaning: The URL targets a disallowed local host or IP literal. Checks: Check for localhost, local/internal suffixes, or an IP address. Next action: Use the public HTTPS hostname of the intended API. ## Data source response type invalid Messages: "Pick plain or json.". Meaning: The response kind is unsupported. Checks: Check the source response kind. Next action: Choose plain text or JSON. ## Plain response has a JSON path Messages: "A plain fetch reads the whole body. Clear the path or switch to json.". Meaning: Plain text fetches read the whole body and cannot use a field path. Checks: Inspect response kind and path. Next action: Clear the path or switch to JSON. ## JSON field too deep Messages: "Path can be at most {max} segments deep.", "Deeper than 8 levels. Pick something closer to the top.". Meaning: The chosen JSON path exceeds eight segments. Checks: Inspect the selected field depth. Next action: Choose a field closer to the root. ## JSON path segment invalid Messages: ""{segment}" cannot be used as a path segment: letters, digits, "-" and "_" only.". Meaning: A path segment contains unsupported characters. Checks: Check each segment for letters, digits, hyphens, or underscores only. Next action: Choose a supported field path. ## Data source key label too long Messages: "Key label must be at most {max} characters.". Meaning: The selected key label exceeds 32 characters. Checks: Inspect the label rather than the secret value. Next action: Use a stored key with a supported label. ## Data source name already used Messages: "A data source named "{name}" already exists.", "A definition named "{name}" already exists.". Meaning: A source with this name already exists. Checks: Inspect existing definitions and command references. Next action: Use the existing source or choose a unique name. ## Data source quota reached Messages: "At most {max} data sources per channel.", "You've reached the {max} data source limit for your channel. Delete one to make room.". Meaning: The channel has reached the 20-source cap. Checks: Inspect definitions and their command references. Next action: Reuse a source or remove an unneeded one before adding another. ## Data source save failed Messages: "Save failed. Network error.", "Failed". Meaning: The source was not confirmed saved. Checks: Reload and inspect the actual definition. Next action: Retry the intended definition change. ## Data source toggle failed Messages: "Toggle failed.". Meaning: The source active-state update failed. Checks: Check the stored active state. Next action: Retry after reloading. ## Data source deletion failed Messages: "Delete of "{name}" failed.". Meaning: The source deletion was not confirmed. Checks: Check whether it still exists and which commands reference it. Next action: Retry only if removal is still intended. ## Sample response cannot be read automatically Messages: "The API answered, but its response could not be read automatically. Paste one below instead.". Meaning: The API answered but automatic sample reading failed. Checks: Inspect a suitable response locally, without sharing secrets. Next action: Paste a suitable sample into the dashboard builder. ## Sample response too large Messages: "That sample is over {max} KB. Paste a shorter one.". Meaning: The pasted sample exceeds the displayed size limit. Checks: Check the limit in the notice. Next action: Paste a smaller response slice. ## Sample response is not JSON Messages: "That is not valid JSON. Fix it and the tree appears here.". Meaning: The sample could not be parsed as JSON. Checks: Check brackets, quoting, and the intended response format. Next action: Correct the JSON or use the appropriate plain response kind. ## Sample has too many fields Messages: "That sample expands to too many fields. Paste a smaller slice.". Meaning: The sample expands into too many selectable fields. Checks: Inspect the sample structure. Next action: Paste a smaller slice. ## Value picker needs a source name Messages: "Give the definition a name first. Picked tokens need it.". Meaning: A token cannot be constructed without a source name. Checks: Check the source name. Next action: Name the definition before selecting a value. ## Fetch test service unavailable Messages: "The fetch service did not answer. Try again in a moment.", "The fetch service did not answer. Try again in a moment.". Meaning: The fetch service did not answer. Checks: Check whether the source is saved and the dashboard reachable. Next action: Wait and retry the test. ## Too many sample tests Messages: "Too many test runs. Each one calls the real API. Wait about 10 seconds and try again.". Meaning: Real API test requests are being made too quickly. Checks: Stop repeated sample requests. Next action: Wait about 10 seconds and test again. ## Test blocked by invalid fields Messages: "Fix the highlighted fields first.". Meaning: Validation prevents the test request. Checks: Inspect highlighted URL, kind, path, and key-label fields. Next action: Correct the fields and test again. ## API denied the sample request Messages: "The API refused the request. Check the URL, and pick the right key under API key if this API needs one.". Meaning: The target API refused the request. Checks: Check URL and selected stored API-key label. Next action: Correct the URL or select the appropriate key in the dashboard. ## API limited the sample request Messages: "Rate limited. Wait a moment and test again.". Meaning: The target API is rate limiting the test. Checks: Avoid repeated requests. Next action: Wait a moment and test again. ## API returned an error Messages: "The API returned an error. Chat sees nothing, unless the token has a |default: {urlfetch:name|default}.". Meaning: The API returned an error result. Checks: Check source URL and any configured token fallback. Next action: Retry later or configure a fallback for missing live values. ## API sample request timed out Messages: "The API timed out. Chat sees nothing, unless the token has a |default: {urlfetch:name|default}.". Meaning: The API did not respond before the deadline. Checks: Check the intended endpoint and token fallback. Next action: Retry later or provide a fallback. ## Source produced no value Messages: "This data source could not produce a value. Until it does, chat shows the token's |default value if it has one, otherwise {urlfetch:name} as typed. Check the web address and the API key, then click Fetch a sample again.". Meaning: The source cannot currently produce the selected value. Checks: Check URL, selected key label, and field path. Next action: Fetch a new sample and choose an available value; review token fallback behavior. - [Commands setup](../setup/commands.md). - [Commands feature](../features/commands.md). - [Connection errors](connection.md).