Troubleshooting and FAQ

I can't connect to my self-managed GitLab instance.

Check two things:

1. The instance URL starts with https:// and is the full base URL (e.g., https://gitlab.example.com).
2. The instance is accessible from the public internet. GitLab instances behind a VPN or firewall are not reachable from the app's backend. See Connect to self-managed GitLab for requirements.

The OAuth pop-up closed before I finished authorizing.

This cancels the flow. Close the panel and try again. The pop-up must stay open until you click Authorize in GitLab. If a pop-up blocker is active in your browser, you can allow pop-ups for the Miro domain and retry.

I connected successfully, but the panel shows no projects.

This is expected on the first connection. A successful connection does not automatically import anything; it only authorizes the app to access your GitLab account. Use Add Issues to Board to link a project or create an issue group. See How-to guides → Link a project.

My Personal Access Token is showing as expired.

Personal Access Tokens have an expiry date set at creation. When yours expires, create a new one in GitLab with the same scopes (read_api and api), then reconnect: go to Connections in the panel, remove the expired connection, and add a new one with the new token. See Manage Connections.

OAuth token refresh failed.

The app refreshes OAuth tokens automatically in the background. If the refresh fails (e.g., the OAuth app was revoked in GitLab, or the user revoked the authorization), you will see an authentication error. Disconnect the affected connection and reconnect via the OAuth flow. See Manage Connections.

I'm being asked to authorize again, even though I already connected.

OAuth authorizations can be revoked in GitLab (by the user or an admin). If that happens, you need to go through the OAuth flow again from Connections in the panel.

Why aren't my GitLab changes showing in Miro?

Sync is manual, not automatic. Changes made in GitLab only appear on the board after you click Sync on a project card, click Sync All in the main panel header, or reload the panel view. The app does not poll GitLab for updates in the background.

Why are my edits in the panel not appearing in GitLab?

Changes saved in the Issue Edit modal are sent to GitLab immediately when you save; they do not wait for a sync. If the change isn't showing in GitLab, you can open the issue directly in GitLab to check.

What fields does sync update?

Sync pulls from GitLab: title, state (open/closed), assignee, labels, and milestone. It does not sync issue descriptions, comments, or attachments.

I triggered sync, but the cards didn't update.

Check that the connection used by that project link is still valid (no auth error in the Connections view). If the connection is fine, try again. If a specific card shows as broken, the underlying GitLab issue may have been deleted. Deleted issues are removed from the board on the next successful sync.

I hit my project limit.

The app shows a modal when this happens. Your options are:

• Start a free trial — available if your team hasn't used one for the next plan tier.

• Upgrade — opens self-serve checkout for Business or the Adaptavist contact page for Enterprise.

• Remove a project — unlink an existing project or delete an issue group to free up a slot, then retry.

For plan limits, see Plans and Licensing.

My trial ended, and now I'm over my limit.

When a trial expires without a purchase, the license reverts to the prior plan. If your team has more projects than the reverted plan allows, an inline banner appears in the panel, showing the Upgrade and Manage projects options. Existing App Cards stay on your board, but you cannot add new ones until the overage is resolved.

I upgraded, but the app still shows my old limit.

Refresh the panel. The license is re-fetched on panel load. If the old limit still appears after a refresh, contact support.

I don't see the OAuth App card in the Connections view.

The OAuth app is created and owned by one person on your Miro team. Only team members who share the same Miro team ID can see it. Confirm that the person who created the OAuth app is on the same Miro team as you (not a separate workspace).

The Redirect URL in the OAuth setup wizard shows "Loading..." and won't populate.

The wizard fetches the Redirect URI from the backend. If it stays on "Loading...", the app's backend is unreachable; this is usually because the app is not fully installed from the Miro marketplace, or there is a network connectivity issue. Confirm the app is installed, and try reopening the panel.

Which scopes do I need for the PAT or OAuth app?

api and read_api. There are no other scopes required. The api scope covers creating and updating issues; read_api covers read operations. Both are explicitly listed in steps 4 and 3 of the OAuth and PAT setup wizards, respectively.

The Create Application button does nothing.

Check that all three fields are filled: GitLab Instance URL, Application ID (Client ID), and Secret (Client Secret). The URL must start with https:// and must not end in a trailing slash.

I deleted a card, and the issue disappeared from the app.

If you clicked Yes, stop tracking in the deletion confirmation modal, the card was intentionally removed from the app's tracking. The underlying GitLab issue is not affected. To bring it back, use Search Issues to find the issue and add it to a new issue group.

If you clicked No, recover, or dismissed the modal without choosing, the card should have been automatically restored. If it wasn't, trigger a Sync on the project — the card will be re-created from GitLab data.

A card is stuck in a loading or broken state.

Trigger a Sync on the project or issue group that contains the card. If the underlying GitLab issue was deleted, the card will be removed from the board on sync. If the issue persists in GitLab, the card should return to a normal state.

I can't edit a card's fields in the Issue Edit modal.

Confirm the connection used by that project link is still authorized. An expired PAT or revoked OAuth token will prevent writes to GitLab. Check the Connections panel and reconnect if needed.