Fehlerbehebung

Diese Seite sammelt die häufigsten Probleme bei der Verwendung von Almirant und ihre Lösungen. Wenn dein Problem hier nicht aufgeführt ist, kontaktiere den Support unter [email protected].

Häufige Probleme

Problem	Ursache	Lösung
Die IDE verbindet sich nicht mit MCP	Falsche URL oder API key	Prüfe, ob die URL https://api.almirant.ai/mcp?projectId=<id> lautet und der API key gültig ist. Stelle sicher, dass das Backend läuft, wenn du localhost verwendest.
„Unauthorized“ bei der MCP-Verbindung	API key abgelaufen oder widerrufen	Erstelle einen neuen API key unter Einstellungen > API Keys und aktualisiere die Konfiguration deiner IDE.
MCP verbindet sich, sieht aber meine Projekte nicht	projectId fehlt oder ist falsch	Prüfe die projectId in der URL. Du findest sie in der Browser-URL, wenn du das Projekt in Almirant öffnest, oder über list_projects ohne projectId.
Ich kann mich nicht anmelden	Google-Konto nicht autorisiert	Deine E-Mail muss in der Liste erlaubter E-Mail-Adressen der Organisation stehen. Bitte den Administrator, sie hinzuzufügen.
Work Items erscheinen nicht auf dem Board	Items archiviert oder Filter aktiv	Prüfe die aktiven Filter in der oberen Board-Leiste. Wenn Items archiviert sind, aktiviere den Filter „Archivierte anzeigen“.
Die KI implementiert die Aufgabe nicht	Work Item ohne ausreichende Beschreibung	Stelle sicher, dass das Work Item eine detaillierte Beschreibung mit Akzeptanzkriterien hat. Ohne Kontext kann die KI nicht bestimmen, was zu implementieren ist.
Drag-and-drop funktioniert nicht auf dem Board	Konflikt mit Browser-Erweiterung	Deaktiviere Erweiterungen, die das DOM ändern (aggressive Ad-Blocker, Barrierefreiheits-Tools, die Ereignisse abfangen). Teste in einem Inkognito-Fenster.
Webhook empfängt keine Ereignisse	URL nicht erreichbar oder HTTPS erforderlich	Prüfe, ob die URL aus dem Internet erreichbar ist und HTTPS verwendet. Sieh im Zustellungsprotokoll unter Einstellungen > Webhooks nach Fehlern.
Webhook gibt 401 zurück	Signatur nicht korrekt geprüft	Verwende für die HMAC-Berechnung den rohen Body (raw), nicht den geparsten Body. Prüfe, ob das Secret mit dem konfigurierten übereinstimmt.
Der Sprint wird nicht geschlossen	Es gibt ungelöste Work Items	Sprints können mit ausstehenden Items geschlossen werden. Nicht abgeschlossene Items können beim Schließen ins Backlog oder in den nächsten Sprint verschoben werden.
Fehler beim Importieren von Leads (CSV)	Falsches Dateiformat	Stelle sicher, dass das CSV Kommas als Trennzeichen verwendet und die erforderlichen Spalten enthält (name, email). Lade die Vorlage auf dem Importbildschirm herunter.
Feedback-Widget erscheint nicht	Script nicht geladen oder Schlüssel falsch	Prüfe, ob das Script vor </body> steht, die URL korrekt ist (https://cdn.almirant.ai/feedback-widget.iife.js) und publicKey gültig ist.
Fehler „CORS“ beim Verbinden über die IDE	Backend konfiguriert CORS nicht für deinen Ursprung	Bei lokalem Backend muss CORS_ORIGIN in deiner .env den richtigen Ursprung enthalten. In Produktion sollte dies nicht auftreten.
Die KI-Planung erzeugt keine Ergebnisse	KI-Anbieter nicht konfiguriert	Gehe zu Einstellungen > Integrationen und verbinde einen KI-Anbieter (Anthropic oder OpenAI). Du benötigst mindestens einen aktiven API key.
Langsame Leistung beim Laden großer Boards	Zu viele sichtbare Items	Verwende Filter, um sichtbare Items zu begrenzen. Archiviere alte abgeschlossene Items. Boards funktionieren am besten mit weniger als 200 sichtbaren Items.

Erweiterte Fehlerbehebung

MCP-Verbindung prüfen

Führe in Claude Code diesen Befehl aus, um zu prüfen, ob die Verbindung funktioniert:

Verwende das Tool list_projects, um meine Projekte aufzulisten

Wenn du deine Projekte siehst, ist die Verbindung korrekt. Andernfalls:

1. Prüfe, ob das Backend läuft (bun run dev:api in der lokalen Entwicklung)
2. Prüfe die URL in .mcp.json oder .claude/settings.json
3. Stelle sicher, dass der API key Berechtigungen für das angegebene Projekt hat
4. Prüfe die Backend-Logs auf Authentifizierungsfehler

Webhooks prüfen

So behebst du einen nicht funktionierenden Webhook:

1. Gehe zu Einstellungen > Webhooks und wähle den Webhook aus
2. Prüfe den Tab Zustellungen auf aktuelle Versuche
3. Klicke auf eine fehlgeschlagene Zustellung, um Details anzuzeigen (request, response, headers)
4. Wenn keine Zustellungen vorhanden sind, stelle sicher, dass die abonnierten Ereignisse zur ausgeführten Aktion passen
5. Nutze einen Dienst wie webhook.site, um zu prüfen, ob Almirant die Anfragen korrekt sendet

Probleme mit dem Feedback Widget

Wenn das Widget nicht erscheint oder nicht funktioniert:

1. Öffne die Browser-Konsole (F12 > Console) und suche nach Fehlern
2. Prüfe, ob das Script korrekt geladen wurde: Gib FeedbackWidget in der Konsole ein. Wenn undefined angezeigt wird, wurde das Script nicht geladen
3. Prüfe, ob FeedbackWidget.isReady() true zurückgibt
4. Stelle sicher, dass publicKey in der Projektkonfiguration korrekt ist
5. Wenn du React verwendest, stelle sicher, dass die Komponente <FeedbackWidget> im Baum eingebunden ist

Browser-Logs

Bei allen Problemen mit der Weboberfläche:

1. Öffne DevTools (F12)
2. Wechsle zum Tab Console und suche nach roten Fehlern
3. Wechsle zum Tab Network und filtere nach fehlgeschlagenen Anfragen (Status 4xx oder 5xx)
4. Wenn du einen Bug meldest, füge Folgendes bei:
   • Screenshot der Konsolenfehler
   • URL der Seite, auf der das Problem auftritt
   • Browser und Version
   • Schritte zur Reproduktion

Tipp

Wenn etwas nicht wie erwartet funktioniert, solltest du zuerst die Browser-Konsole und die Backend-Logs prüfen. Die meisten Probleme lassen sich mit Informationen aus diesen beiden Quellen lösen.