Troubleshooting

This page collects the most common problems when using Almirant and their solutions. If your problem is not listed here, contact support at [email protected].

Common Problems

Problem	Cause	Solution
IDE does not connect to MCP	Incorrect URL or API key	Verify that the URL is https://api.almirant.ai/mcp?projectId=<id> and that the API key is valid. Check that the backend is running if you are using localhost.
"Unauthorized" when connecting to MCP	Expired or revoked API key	Generate a new API key in Settings > API Keys and update your IDE configuration.
MCP connects but does not see my projects	Missing or incorrect projectId	Verify the projectId in the URL. You can get it from the browser URL when opening the project in Almirant, or by using list_projects without projectId.
Cannot log in	Google account not authorized	Your email must be on the organization's allowed email list. Contact the administrator to have it added.
Work items do not appear on the board	Archived items or active filter	Check the active filters in the board's top bar. If the items are archived, enable the "Show archived" filter to see them.
AI does not implement the task	Work item without sufficient description	Make sure the work item has a detailed description with acceptance criteria. Without context, the AI cannot determine what to implement.
Drag and drop does not work on the board	Browser extension conflict	Disable extensions that modify the DOM (aggressive ad blockers, accessibility tools that intercept events). Try in an incognito window.
Webhook does not receive events	URL not accessible or HTTPS required	Verify that the URL is accessible from the internet and uses HTTPS. Check the delivery log in Settings > Webhooks to see the errors.
Webhook returns 401	Signature not verified correctly	Make sure to use the raw body to calculate the HMAC signature, not the parsed body. Verify that the secret matches the one configured.
Sprint does not close	There are unresolved work items	Sprints can be closed with pending items. Incomplete items can be moved to the backlog or the next sprint when closing.
Error importing leads (CSV)	Incorrect file format	Verify that the CSV uses commas as delimiters and has the required columns (name, email). Download the template from the import screen.
Feedback widget does not appear	Script not loaded or incorrect key	Verify that the script is placed before </body>, that the URL is correct (https://cdn.almirant.ai/feedback-widget.iife.js), and that the publicKey is valid.
"CORS" error when connecting from the IDE	Backend does not configure CORS for your origin	If you are using the local backend, verify that CORS_ORIGIN in your .env includes the correct origin. In production, this should not happen.
AI planning does not generate results	AI provider not configured	Go to Settings > Integrations and connect an AI provider (Anthropic or OpenAI). You need at least one active API key.
Slow performance loading large boards	Too many visible items	Use filters to limit visible items. Archive old completed items. Boards work best with fewer than 200 visible items.

Advanced Debugging

Verify the MCP Connection

Run this command in Claude Code to verify that the connection works:

Use the list_projects tool to list my projects

If you see your projects, the connection is correct. If not:

1. Verify that the backend is running (bun run dev:api for local development)
2. Check the URL in .mcp.json or .claude/settings.json
3. Verify that the API key has permissions for the specified project
4. Check the backend logs for authentication errors

Verify Webhooks

To debug a webhook that is not working:

1. Go to Settings > Webhooks and select the webhook
2. Check the Deliveries tab to see recent attempts
3. Click on a failed delivery to see the details (request, response, headers)
4. If there are no deliveries, verify that the subscribed events match the action you are performing
5. Use a service like webhook.site to test that Almirant sends the requests correctly

Feedback Widget Issues

If the widget does not appear or does not work:

1. Open the browser console (F12 > Console) and look for errors
2. Verify that the script loaded correctly: type FeedbackWidget in the console. If it is undefined, the script did not load
3. Verify that FeedbackWidget.isReady() returns true
4. Check that the publicKey is correct in the project configuration
5. If you are using React, make sure the <FeedbackWidget> component is mounted in the tree

Browser Logs

For any problem with the web interface:

1. Open DevTools (F12)
2. Go to the Console tab and look for errors in red
3. Go to the Network tab and filter for failed requests (status 4xx or 5xx)
4. If you are reporting a bug, include:
   • Screenshot of the console errors
   • URL of the page where it occurs
   • Browser and version
   • Steps to reproduce

Tip

If something is not working as expected, the first step is always to check the browser console and the backend logs. Most problems are resolved with information from these two sources.