Error handling

When the Miro Web SDK handles input that it cannot process correctly, it throws an error.
Error messages help you understand what went wrong, where, and why. They give you context to make it easier to troubleshoot issues.

This is a reference overview of error messages that the Miro Web SDK can throw to notify about a failed operation.
Error messages are grouped in sections:

Authorization
Error notifications ranging from missing permissions, to users rejecting to grant the required permissions to an app during the installation, to users lacking authorization to interact with apps or boards.
Installation
Error notifications about issues occurring when installing an app to the board.
Initialization
Error notifications about failed initialization of the Web SDK, of the instance of an item, and so on.
They can occur when a command initiates an action on an object that isn't yet available on the board.
User interface
Error notifications about a failed interaction with a UI component of the board.
For example: the board UI may be unresponsive, or the app may attempt to interact with an element that isn't associated with the ID of the app.
CRUD operations
Error notifications about failed attempts to create, read, update, or delete a board item or a resource.
Invalid input
Error notifications about failed operations because of passing invalid arguments.
For example: incomplete, malformed, or outside the range of the expected values.
Rate limiting
Errors notifications about your app using up allocated resources too quickly.
Check how you can mitigate the issue by reducing the number of calls per minute or per hour.
Backend
Error notifications about failed data exchange with the server.
Unknown ID
Errors notifications about messing IDs to identify a board item or an app.
If the Miro Web SDK attempts to perform an action on, or exchange data with an item or an app, it identifies the target object by its unique ID.
If the ID reference isn't valid, or if it's not found, the operation fails.
Unsupported
Errors notifications about performing actions that aren't supported.
For example: actions that don't comply with existing constraints, or that aren't available.
Unknown error
In this case, the error message includes the original payload to provide a starting point for troubleshooting.

Authorization

Error message	Description
`The authorization request failed, or the user rejected it.`	The end user didn't complete installing the app to the board when prompted through the UI. Or: the app wasn't granted the required permissions. Or: the app authorization information is invalid.
`Cannot execute ${command}, because the ${appId} app doesn't have the following permission: ${requiredScope}.`	The app wasn't granted a permission that enables executing the specified command. For example: Commands that access board items require boards:read Commands that modify board items require boards:write Commands that start and stop audio recording require microphone:listen
`The user doesn't have the necessary permissions in the team to obtain an ID token.`	The user trying to access the app lacks one or more required permissions that the app needs to work as expected.
`The user doesn't have the necessary permissions to hide content in frames.`	The `showContent` property of frame items requires permissions that are available to board owners and co-owners on a Consultant or Enterprise plan.
`The user is unauthorized in Miro. Only authorized users can obtain ID tokens.`	The user trying to access the app hasn't been authorized as a Miro user.
`The (${name}) feature is available only on paid plans. To use this feature, upgrade your current plan to a paid one.`	The feature that you're trying to use isn't available on your current plan. Upgrade to a paid plan to access it.
`The current user doesn't have enough permissions to access the feature ${feature}.`	The feature requires additional permissions that the current user hasn't been granted. The user needs to first request the additional permissions, and then they can access the feature.

Installation

Error message	Description
`The "${appName}" app (${appId}) isn't installed for the "${teamName}" team. To use the app with this team, install it for them.`	The currently selected team cannot access the app. Install it for the team to make it available.

Initialization

Error message	Description
`The Web SDK hasn't initialized.`	The Miro Web SDK hasn't initialized on the board, and it's not available.
`The item instance hasn't initialized.`	The app attempted to interact with the instance of an item that hasn't initialized on the board, and that's not available.
`The drag state hasn't initialized.`	The app attempted to drag a board item. However, the drag state hasn't initialized on the board, and it's not available.
`Cannot execute the command, because the app iframe hasn't initialized.`	The iframe that the app controls hasn't initialized on the board, and it's not available.
`Cannot open the modal or the panel, because no iframe is registered with the ${type}.`	The app attempted to open an iframe to display a modal or a panel. However, no iframe is registered to interact with the app and the Miro Web SDK 2.0.
`Cannot load the app, because the method to load it is called on a destroyed app instance.`	It wasn't possible to load and start the app, because the app instance no longer exists.

User interface

Error message	Description
`The app is trying to close a modal, but there's no open modal associated with this app.`	Either the app attempted to close a modal that the app cannot interact with. Or there are currently no open modals that the app can close. The modals that an app can interact with must be registered with the app.
`The app is trying to close a panel, but there's no open panel associated with this app.`	Either the app attempted to close a panel that the app cannot interact with. Or there are currently no open panels that the app can close. The panels that an app can interact with must be registered with the app.
`Cannot open the panel. The board GUI may be inactive or hidden.`	Since the board UI is inactive or hidden, the panel toolbar is not available. Therefore, it's not possible to trigger opening a panel.
`You can drag on the board only items from panels that are opened with the 'openPanel' method.`	Apps must open a panel with the `openPanel` method. Draggable items can be included only in panels opened with `openPanel`.

CRUD operations

Error message	Description
`Cannot set item ${id} as a child, because the item isn't inside the parent frame.`	The app attempted to set an item as a child of a parent frame. However, the item the ID refers to isn't inside the target frame. Therefore, it cannot be a child of the frame.
`Cannot set item ${id} as a child, because the item doesn't exist.`	The app attempted to set an item as a child of a parent frame. However, the item the ID refers to doesn't exist on the board.
`Cannot move the ${type} item with ID (${id}) to the specified location, because it's a child of another board item. Remove the child item from its parent, and then move it.`	The app attempted to move an item to a new position on the board. The operation failed, because the item is a child of a parent item. First, remove the child item from its parent. Then, the app can set new coordinates for the item, and `sync` it to update its position on the board.
`Cannot create the image.`	The app attempted to create an image item, but it failed to correctly retrieve the image the URL points to.
`Cannot upload the image: ${msg}.`	The app attempted to update an image item, but it failed to correctly retrieve the updated image the URL points to.
`Cannot change this property, because it's read-only: "${prop}"`	The app attempted to update a property that is available with read-only access.
`Cannot remove the ${type} item (id=${id}).`	The app attempted to remove a board item, but the item the ID refers to may not exist on the board, or it may not be possible to retrieve it.
`The title must be unique. Specify a different title for the tag.`	The title that the app attempted to assign to a tag already exists.
`Cannot create more tags. The board has reached the limit of ${limit} tags.`	It's not possible to have more than 100 tags in total on a board.
`The canvas API returned an unknown color: ${color}.`	The backend returned a color name for the tag that isn't included in the list of allowed tag colors.
`Cannot resolve the embed URL ${url}. Please try again later.`	It's not possible to correctly resolve the URL pointing to the content of an embed item. This may be a temporary issue. Retry the operation at a later time.
`Cannot change parent, because item ${id} is locked by another client.`	The app attempted to update a frame containing one or more child items. At the same time, a different user accessed a child item to modify it. When the user finishes editing the child item, it is unlocked. Then it's possible to update the parent frame.
`Cannot commit the update, because item ${id} is locked by another client.`	The app attempted to update an item. At the same time, a different user accessed the same item to modify it. When the user finishes editing the item, it is unlocked. Then it's possible to update it.
`The data storage limit for "${featureName}" has been exceeded.`	The app attempted to store more metadata than the allowed limit to either `appdata` or `item metadata`. For more information, see `setAppData` and `setMetadata`
`Cannot attach a locked item to a parent, because another client is locking item ${id}.`	You're trying to attach an item to a parent. However, the item is currently in a locked state. \nAnother user or app may be locking the item; therefore, the operation fails.
`Cannot detach a locked item from its parent, because another client is locking item ${id}.`	You're trying to detach an item from its parent. However, the item is currently in a locked state. \nAnother user or app may be locking the item; therefore, the operation fails.
`Cannot update the properties of item ${id}, because another client is locking at least one of the item's children:`	You're trying to update a parent item. However, one or more child items of the parent are currently in a locked state. \nAnother user or app may be locking the child items; therefore, the operation fails.
`Cannot commit the update, because another client is locking item ${id}.`	You're trying to update an item. However, the item is currently in a locked state. \nAnother user or app may be locking the item; therefore, the operation fails.
`Cannot resize the frame (${id}) to the specified size, because one or more children would exist outside the

Invalid input

Error message	Description
`The payload isn't valid, because the 'type' property is missing.`	The app attempted to pass a board item as an argument, but the item lacked the required `type` property, which defines the specific type of board item.
`The ${prop} style property is unknown.`	The app attempted to pass a board item as an argument, but the item includes a property that doesn't belong to the item, or that the Web SDK cannot recognize.
`The value of the ${prop} style property isn't valid.`	The app attempted to pass a board item as an argument, but the item includes a property with an invalid value.
`"svgIcon" isn't a valid SVG element: ${svgIcon}.`	The app attempted to upload or retrieve an SVG file that failed validation: it may be malformed or corrupt.
`The URL isn't valid: ${url}.`	The URL that the app interacted with isn't a valid URL.
`The URL for the ${name} app isn't valid. The URL must start with "https" or "http://localhost".`	The URL you set on the app settings page under App URL must use the HTTPS transport protocol. HTTP is allowed only when the URL points to a local environment.
`The date format isn't valid. Specify dates as YYYY-MM-DD. Example: 2021-08-29`	The date assigned to the `dueDate` property of the card item must be in the `YYYY-MM-DD` format.
`The specified item has no valid ID. Cannot perform actions on items with no valid ID.`	The app attempted to perform an action—for example: update or remove—on a board item whose ID is invalid. The item may no longer be available on the board.
`This is an unexpected item type: ${widgetType}`	The board item that was returned doesn't correspond to the expected `type` for the item.
`The argument you're passing isn't valid. Pass the item(s) you want to zoom to.`	The app attempted to zoom to one or more board items. However, the arguments that were passed to the `zoomTo` method weren't valid board items.
`You're passing one or more frames to board.${command}(). Frames cannot move to the back or the front. Other supported items can. Pass an item that supports sending to front and moving to back.`	It's not possible to move frames to the front or to the back. Pass one or more board items other than frame to the bringToFront or sendToBack methods.
`Users cannot follow themselves.`	A user cannot be both the follower and the followed user at the same time.
`The current user is already following another user. To start following another user, stop the current following session first, and start a new one.`	You can follow only one user at a time during a given following session. To follow a different user: Unfollow the user in the current session. Start a new session to follow the different user.
`There's no following session in progress.`	You're currently not following any user. To check if a following session is in progress: invoke `isFollowing`.
`The user you're trying to follow isn't online in the current session.`	The active following session is following a user who isn't online on the board.
`Set either position or snapTo. It's not possible to set both properties at the same time.`	When setting the location of start and end terminal points of a connector, define either `position` coordinates, or `snapTo` predefined snap points.
`snapTo cannot be undefined.`	`snapTo` accepts values from a list of options. \nYou cannot assign `undefined` as a value.

Rate limiting

Error message	Description
`The API rate limit was exceeded. Requests can use up to ${limit} credits in total per hour.`	The app made too many calls to the Miro Web SDK. Wait until new credits are issued.
`The API rate limit was exceeded. Requests can use up to ${limit} credits in total per minute.`	The app made too many calls to the Miro Web SDK. Wait until new credits are issued.

Backend and server

Error message	Description
`An error occurred while retrieving an ID token.`	It's not possible to correctly retrieve the app ID token from the server.
`Cannot upload the ${previewUrl} previewUrl image.`	It's not possible to successfully upload an image to update the preview of an embed item.

Unknown ID

Error message	Description
`Cannot update the app, because the corresponding client ID ${pluginId} wasn't found.`	The Miro Web SDK identifies apps by their client ID. No client ID was retrieved for the app that attempted to update. Therefore, it's not possible to apply the update.
`Cannot retrieve app data for this app. The app doesn't have a valid client ID.`	The Miro Web SDK identifies apps by their client ID. No valid client ID was retrieved for the app. Therefore, it's not possible to retrieve any app data.
`Cannot set app data for this app. The app doesn't have a valid client ID.`	The Miro Web SDK identifies apps by their client ID. No valid client ID was retrieved for the app. Therefore, it's not possible to set any data for the app.
`Cannot retrieve metadata for this item. The app doesn't have a valid client ID.`	The Miro Web SDK identifies apps by their client ID. No valid client ID was retrieved for the app. Therefore, it's not possible to retrieve any board item metadata that the app previously set.
`Cannot find the item with ID: ${id}.`	It wasn't possible to retrieve the board or the tag item the ID refers to.

Unsupported

Error message	Description
`Unsupported: during creation you can set "width", but not "height".`	It's possible to set only `width` when creating the board item. `height` is calculated automatically, based on `width`.
`Change either "width", or "height". It's not possible to change both properties at the same time.`	It's possible to change either `width`, or `heigth` when updating the board item. You can update both properties one at a time, in two subsequent calls.
`Set either ${cap}.position, or ${cap}.snapTo. It's not possible to set both properties at the same time.`	You can set the connector cap on the border of the shape by either defining `x` and `y` position, or by using a predefined `snapTo` value. You cannot assign values to both properties.
`${cap}.snapTo cannot be undefined.`	If you set the connector cap on the border of the shape by using `snapTo`, you must assign the property one of the following values: `top` `left` `bottom` `right` `auto` .
`The specified embed type is unsupported. Supported embed types: video, audio, and web pages.`	It's possible to generate embed items containing video, audio, or a web page (URL link). Embed items don't support other content types.
`This is an unknown shape type: ${shape}. Specify a supported shape type.`	The geometric shape type isn't one of the supported ones for shape items. Assign to `shape.shape` one of the supported geometric shape values.
`sync() not supported for shape '${shape}'.`	You tried to update the properties of an experimental shape. \n \nIn the `experimental` namespace, some shapes may be available as read-only objects: It's possible to

Unknown error

Error message	Description
`An unknown error occurred: ${payload}.`	An unknown error was thrown. The original payload is included to provide a starting point for troubleshooting.