Error handling

An overview of error messages that the Web SDK can throw when an operation fails.

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 messageDescription
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 board:read
  • Commands that modify board items require board: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 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.

Installation

Error messageDescription
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 messageDescription
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 messageDescription
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 messageDescription
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 resize the frame (${id}) to the specified size, because one or more children would exist outside the parent frame.The app attempted to resize a parent frame containing child items, and one or more children would fall outside the parent frame after resizing it.
This isn't allowed, because it would break the parent/child relationship between the items.
To break the relationship, explicitly remove the child item(s) from the parent frame.
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.

Invalid input

Error messageDescription
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-29The 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.

Rate limiting

Error messageDescription
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 messageDescription
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 messageDescription
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 find the item with ID: ${id}.It wasn't possible to retrieve the board or the tag item the ID refers to.

Unsupported

Error messageDescription
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.
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.
The item type is unsupported. Specify a supported item type. Received: ${itemType}.The app attempted to interact with a board item that isn't supported. Specify one of these supported board item types, instead.
The specified command is unsupported: ${command}.The app invoked a command that isn't supported.
The specified command is unknown: ${command}.The app invoked a command that isn't known.

Unknown error

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

Did this page help you?