Client-Server Fehlersuche

Wenn AGYNAMIX Invoicer im Client-Modus keine Verbindung zum Host-Server herstellen kann, hilft diese Seite bei der systematischen Fehlersuche. Die Anwendung enthält einen Verbindungsprüf-Assistenten (unter Einstellungen → Server → Verbindung prüfen), der Dich hierher verlinkt, wenn ein Prüfschritt fehlschlägt.

Die Seite ist aber auch ohne den Assistenten nützlich — Du kannst die Checklisten und Erklärungen unabhängig davon durchgehen.

TL;DR — Die drei häufigsten Ursachen:

  1. Server läuft nicht – Stelle sicher, dass der Host-Modus auf dem Server-Rechner aktiviert ist (erfordert Ultimate-Lizenz).
  2. Firewall blockiert – Ports 8080 (HTTP) und 8443 (HTTPS) müssen auf dem Server-Rechner offen sein.
  3. Falscher Token – Der Host-API-Token im Client muss exakt mit dem Token auf dem Server übereinstimmen.

Architektur im Überblick

Im Client-Server-Modus kommuniziert eine Invoicer-Instanz im Client-Modus über das Netzwerk mit einer zweiten Instanz im Host/Server-Modus. Der Host ist der führende Rechner — er hält die Datenbank und stellt eine API bereit. Der Client verbindet sich dorthin.

Netzwerkarchitektur: Client verbindet sich über HTTP (8080) und HTTPS (8443) mit dem Host

Standardmäßig lauscht der Host-Server auf zwei Ports gleichzeitig:

  • Port 8080 – HTTP (unverschlüsselt, als Fallback und für Diagnose)
  • Port 8443 – HTTPS mit TLS (verschlüsselte Verbindung, empfohlen)

Der Client bevorzugt automatisch HTTPS, kann aber auf HTTP zurückfallen, wenn kein TLS verfügbar ist.

Was der Verbindungs-Assistent prüft

Der Assistent führt sieben Prüfungen in zwei Schritten durch:

Ablauf der Verbindungsprüfung: Schritt 1 testet die Netzwerk-Erreichbarkeit, Schritt 2 die Authentifizierung

Wenn eine Prüfung fehlschlägt, zeigt der Assistent eine Fehlermeldung und verlinkt auf den passenden Abschnitt dieser Seite.

Voraussetzungen

Bevor Du mit der Fehlersuche beginnst, prüfe diese Grundlagen:

  • ☐ Der Host-Rechner läuft und AGYNAMIX Invoicer ist gestartet.
  • ☐ Der Host/Server-Modus ist aktiviert (unter Einstellungen → Server). Dafür ist eine Ultimate-Lizenz erforderlich.
  • ☐ Du kennst die IP-Adresse oder den Hostnamen des Server-Rechners.
  • ☐ Die Standard-Ports sind nicht geändert (HTTP: 8080, HTTPS: 8443) — oder Du kennst die geänderten Ports.
  • ☐ Der Host-API-Token ist bekannt und stimmt auf beiden Seiten überein.
  • ☐ Auf dem Host existiert mindestens ein Benutzerkonto mit gesetztem Passwort.
  • ☐ Client und Host befinden sich im selben Netzwerk (oder ein VPN verbindet sie).

Verbindungsfehler

Die folgenden Abschnitte beschreiben die Fehler, die beim Verbindungstest (Schritt 1) des Assistenten auftreten können.

Verbindung abgelehnt

Fehlermeldung im Assistenten: Verbindung abgelehnt – der Server läuft möglicherweise nicht oder der Port ist falsch.

Das bedeutet, dass der Client-Rechner den Host-Rechner im Netzwerk zwar erreicht, aber auf dem angegebenen Port niemand antwortet. In der Praxis sind das die häufigsten Gründe:

Was Du prüfen solltest:

  1. Läuft der Server? Öffne AGYNAMIX Invoicer auf dem Host-Rechner und prüfe unter Einstellungen → Server, ob der Host-Modus aktiv ist. Der Server-Status sollte als „Läuft” angezeigt werden.
  2. Stimmen die Ports? Vergleiche die Port-Nummern im Verbindungsprüf-Assistenten mit den tatsächlichen Ports, die der Server anzeigt. Wenn Du die Ports geändert hast, müssen sie übereinstimmen.
  3. Firewall auf dem Server-Rechner: Besonders unter Linux und Windows können lokale Firewalls den Zugriff auf die Ports 8080/8443 blockieren, auch wenn der Server läuft.
    • Windows: Prüfe Windows Defender Firewall → Erweiterte Einstellungen → Eingehende Regeln. Erstelle ggf. eine Regel für Port 8080 und 8443.
    • Linux: Prüfe mit sudo ufw status oder sudo iptables -L ob die Ports offen sind.
    • macOS: Die eingebaute Firewall blockiert meist nur eingehende Verbindungen für unbekannte Apps. Erlaube AGYNAMIX Invoicer unter Systemeinstellungen → Netzwerk → Firewall.
  4. Erster Test auf dem Server-Rechner: Öffne auf dem Server-Rechner einen Browser und rufe http://127.0.0.1:8080/api/v1/health auf. Wenn Du eine JSON-Antwort mit der Server-Version siehst, läuft der Server korrekt. Alternativ im Terminal: 
    curl http://127.0.0.1:8080/api/v1/health
    Wenn das funktioniert, aber der Client von einem anderen Rechner nicht verbinden kann, liegt das Problem im Netzwerk oder der Firewall.

Tipp: Auf dem Client-Rechner kannst Du dieselbe Prüfung durchführen — im Browser http://<server-ip>:8080/api/v1/health aufrufen oder im Terminal:

curl http://<server-ip>:8080/api/v1/health

Für HTTPS teste mit https://<server-ip>:8443/api/v1/health. Der Browser wird dabei warnen, dass die Verbindung nicht sicher sei — das ist erwartet, weil der Server ein selbstsigniertes Zertifikat verwendet. Klicke auf „Erweitert” → „Trotzdem fortfahren” (der genaue Text variiert je nach Browser), um die Seite zu öffnen. Wenn Du die JSON-Antwort siehst, funktioniert die HTTPS-Verbindung korrekt.

Zeitüberschreitung (Timeout)

Fehlermeldung im Assistenten: Zeitüberschreitung – der Server ist möglicherweise nicht erreichbar oder eine Firewall blockiert die Verbindung.

Ein Timeout bedeutet, dass der Client eine Anfrage gesendet hat, aber innerhalb von 5 Sekunden keine Antwort kam. Im Unterschied zu „Verbindung abgelehnt” kommt hier gar keine Antwort zurück — das Paket verschwindet still im Netzwerk.

Was Du prüfen solltest:

  1. IP-Adresse korrekt? Stelle sicher, dass die IP-Adresse des Servers stimmt. Ein Tippfehler führt dazu, dass Pakete an eine nicht existierende Adresse gesendet werden.
  2. Ping-Test: Teste die grundlegende Netzwerkverbindung mit ping <server-ip>. Wenn der Ping nicht durchkommt, liegt ein Netzwerk- oder Firewall-Problem vor.
  3. Firewall mit DROP-Regel: Manche Firewalls verwerfen Pakete still (DROP statt REJECT). Das führt zu Timeouts statt zu „Verbindung abgelehnt”. Prüfe die Firewall-Regeln auf dem Server.
  4. Unterschiedliche Subnetze: Wenn Client und Host in verschiedenen Netzwerksegmenten sind (z. B. WLAN vs. LAN), kann ein Router oder eine Netzwerk-Isolation den Zugriff verhindern.
  5. VPN-Verbindung aktiv? Falls Du über VPN verbindest, stelle sicher, dass die VPN-Verbindung steht und der Datenverkehr zum Host-Netzwerk geroutet wird.

Tipp: Funktioniert HTTP (Port 8080) aber HTTPS (Port 8443) hat einen Timeout? Dann blockiert wahrscheinlich die Firewall nur den HTTPS-Port. Öffne beide Ports.

TLS-Handshake fehlgeschlagen

Fehlermeldung im Assistenten: TLS-Handshake fehlgeschlagen – der Server unterstützt möglicherweise kein HTTPS auf diesem Port.

Dieser Fehler tritt auf, wenn der Client versucht, eine verschlüsselte HTTPS-Verbindung aufzubauen, aber der TLS-Handshake scheitert. Das ist fast immer ein Port-Problem.

Was Du prüfen solltest:

  1. HTTPS auf dem richtigen Port? Der häufigste Fehler: Du hast den HTTP-Port (8080) im HTTPS-Feld eingetragen oder umgekehrt. HTTP und HTTPS sind unterschiedliche Protokolle — sie laufen auf getrennten Ports.
    • HTTP (Standard): Port 8080
    • HTTPS (Standard): Port 8443
  2. HTTP funktioniert? Prüfe zuerst, ob HTTP (Port 8080) funktioniert. Wenn ja, ist der Server erreichbar, und das Problem liegt nur bei der TLS-Konfiguration.
  3. TLS-Zertifikat: Der Server erstellt beim ersten Start automatisch ein selbstsigniertes TLS-Zertifikat. Wenn das Zertifikat beschädigt ist oder fehlt, schlägt der Handshake fehl. In diesem Fall starte den Server neu — er generiert bei Bedarf ein neues Zertifikat.

Gut zu wissen: AGYNAMIX Invoicer verwendet ein selbstsigniertes Zertifikat (Trust-On-First-Use). Das ist für den Einsatz im lokalen Netzwerk normal und sicher. Der Client akzeptiert dieses Zertifikat automatisch.

DNS-Auflösung fehlgeschlagen

Fehlermeldung im Assistenten: DNS-Auflösung fehlgeschlagen – die Serveradresse konnte nicht aufgelöst werden.

Das bedeutet, dass der eingegebene Hostname nicht in eine IP-Adresse aufgelöst werden konnte.

Was Du prüfen solltest:

  1. Tippfehler im Hostnamen? Prüfe die Schreibweise. Ein servre.local statt server.local reicht aus.
  2. IP-Adresse verwenden: Anstatt eines Hostnamens kannst Du auch direkt die IP-Adresse des Servers eingeben (z. B. 192.168.1.10). Das umgeht DNS-Probleme komplett.
  3. DNS-Server erreichbar? Prüfe, ob DNS grundsätzlich funktioniert: nslookup <hostname> oder ping <hostname>.
  4. mDNS / .local-Adressen: Hostnamen wie meinrechner.local funktionieren nur, wenn mDNS (Bonjour/Avahi) im Netzwerk aktiv ist. In manchen Unternehmens-Netzwerken ist das deaktiviert.

Empfehlung: Für die zuverlässigste Verbindung verwende die direkte IP-Adresse des Servers. Hostnamen können sich ändern oder in manchen Netzwerken nicht auflösbar sein.

Unbekannter Fehler

Fehlermeldung im Assistenten: Ein unerwarteter Fehler ist aufgetreten.

Dieser Fehler tritt auf, wenn keiner der bekannten Fehlermuster erkannt wurde.

Was Du prüfen solltest:

  1. Fehlerdetails ansehen: Klicke im Assistenten auf das Fehler-Symbol neben der fehlgeschlagenen Prüfung. Der Dialog zeigt die technische Fehlermeldung, die bei der Analyse helfen kann.
  2. Server-Version prüfen: Stelle sicher, dass Client und Host dieselbe Version von AGYNAMIX Invoicer verwenden. Versionsunterschiede können zu unerwarteten Fehlern führen.
  3. Server neu starten: Ein Neustart des Servers kann vorübergehende Probleme beheben.
  4. Logs prüfen: Auf dem Server-Rechner kann die Log-Datei von AGYNAMIX Invoicer weitere Details enthalten.

HTTP-Statuscode-Fehler

Die folgenden Fehler treten auf, wenn der Server erreichbar ist und antwortet, aber die Anfrage ablehnt. Diese Fehler erscheinen typischerweise im Authentifizierungs-Schritt (Schritt 2) des Assistenten.

Fehler 401 — Nicht autorisiert

TL;DR: Der Host-API-Token oder die Zugangsdaten stimmen nicht. Vergleiche Token und Passwort mit den Einstellungen auf dem Server.

Ein 401-Fehler bedeutet, dass der Server die Autorisierung abgelehnt hat. Das kann zwei verschiedene Ursachen haben:

Token-Validierung schlägt fehl (Schritt „Token-Validierung”):

Der Host-API-Token, den Du im Assistenten eingegeben hast, stimmt nicht mit dem Token auf dem Server überein. Der Token wird bei allen API-Anfragen als Autorisierung gesendet — wenn er falsch ist, scheitert bereits die erste Prüfung.

  • Öffne auf dem Server-Rechner die Einstellungen (Einstellungen → Server) und kopiere den Host-API-Token.
  • Trage diesen Token exakt im Client ein. Achte auf unsichtbare Leerzeichen am Anfang oder Ende.

Benutzer-Login schlägt fehl (Schritt „Benutzer-Login”):

Benutzername oder Passwort sind falsch.

  • Prüfe, ob der Benutzername exakt stimmt (Groß-/Kleinschreibung beachten).
  • Prüfe, ob für diesen Benutzer auf dem Host tatsächlich ein Passwort gesetzt ist.
  • Wurde das Passwort kürzlich geändert? Der Assistent verwendet die gespeicherten Zugangsdaten — diese müssen aktualisiert werden.

Fehler 403 — Zugriff verweigert

TL;DR: Das Benutzerkonto ist möglicherweise deaktiviert oder hat keine ausreichenden Berechtigungen.

Ein 403-Fehler bedeutet, dass die Autorisierung zwar gültig ist, der Zugriff aber trotzdem verweigert wird.

Was Du prüfen solltest:

  1. Benutzerkonto aktiv? Prüfe auf dem Server-Rechner, ob das Benutzerkonto aktiv ist und nicht deaktiviert oder gelöscht wurde.
  2. Berechtigungen ausreichend? Der Benutzer benötigt mindestens grundlegende Leseberechtigungen, um den Client-Modus nutzen zu können. Prüfe die Rolleneinstellungen auf dem Server.

Fehler 404 — Nicht gefunden

TL;DR: Versionsunterschied zwischen Client und Server. Aktualisiere beide auf dieselbe Version.

Ein 404-Fehler bei der API bedeutet, dass der Server den angefragten Endpunkt nicht kennt. Das passiert typischerweise, wenn Client und Server unterschiedliche Versionen verwenden und die API-Endpunkte sich geändert haben.

Was Du prüfen solltest:

  1. Versionen vergleichen: Stelle sicher, dass Client und Host exakt dieselbe Version verwenden. Die Version findest Du unter Hilfe → Über AGYNAMIX Invoicer.
  2. Beide aktualisieren: Wenn die Versionen unterschiedlich sind, aktualisiere beide Instanzen auf die neueste Version.

Fehler 500 — Interner Serverfehler

TL;DR: Problem auf der Serverseite. Starte den Server neu und prüfe die Logs.

Ein 500-Fehler deutet auf ein unerwartetes Problem auf dem Server hin.

Was Du prüfen solltest:

  1. Server neu starten: Ein Neustart von AGYNAMIX Invoicer auf dem Server-Rechner behebt oft vorübergehende Probleme.
  2. Speicherplatz prüfen: Wenn die Festplatte auf dem Server voll ist, kann die Datenbank nicht mehr arbeiten.
  3. Logs prüfen: Die Server-Logs enthalten die vollständige Fehlermeldung inkl. Stack-Trace.

Authentifizierungs-Details

Im zweiten Schritt des Assistenten werden vier Prüfungen durchgeführt. Hier sind die Details zu jeder einzelnen:

Token-Validierung

Der Client sendet den Host-API-Token als Authorization: Bearer-Header an den Server. Wenn der Token gültig ist, antwortet der Server mit der Liste der Benutzerkonten.

Häufige Probleme:

  • Token wurde auf dem Server geändert, aber nicht im Client aktualisiert.
  • Unsichtbare Zeichen (Leerzeichen, Zeilenumbrüche) am Anfang oder Ende des Tokens.
  • Der Token wurde aus einer E-Mail oder einem Messenger kopiert und dabei gekürzt.

Kontenliste

Nach erfolgreicher Token-Validierung zeigt der Assistent die Anzahl der auf dem Server verfügbaren Benutzerkonten an. Wenn keine Konten gefunden werden, müssen zuerst Benutzer auf dem Server angelegt werden.

Benutzer-Login

Der Client sendet Benutzername und Passwort an den Server. Bei Erfolg erhält er ein temporäres Sitzungs-Token.

Häufige Probleme:

  • Der Benutzer existiert nicht auf dem Server → muss zuerst angelegt werden.
  • Für den Benutzer wurde kein Passwort gesetzt → Passwort in der Benutzerverwaltung auf dem Server setzen.
  • Tippfehler im Benutzernamen oder Passwort.

Sitzungs-Validierung

Mit dem Sitzungs-Token prüft der Client, ob die Sitzung gültig ist und welche Berechtigungen der Benutzer hat. Der Assistent zeigt die Anzahl der verfügbaren Berechtigungen an.

Hinweis zu Berechtigungen: Wenn der Assistent eine Warnung zeigt, dass der Benutzer möglicherweise nicht genügend Berechtigungen hat, bedeutet das, dass grundlegende Leseberechtigungen fehlen (z. B. Dokumente lesen, Kunden lesen). Der Client-Modus funktioniert nur eingeschränkt, wenn diese fehlen. Passe die Rolleneinstellungen auf dem Server an.

Sitzungs-Timeout: Sitzungen laufen nach 5 Minuten Inaktivität ab, und haben ein Höchstalter von 8 Stunden. Im normalen Betrieb hält der Client die Sitzung automatisch mit Heartbeats aktiv. Im Assistenten kann eine kurze Inaktivität aber zum Ablauf führen — ein erneuter Login ist dann ausreichend.

TLS und Zertifikate

AGYNAMIX Invoicer verwendet für die Client-Server-Kommunikation standardmäßig TLS-Verschlüsselung (HTTPS auf Port 8443).

Wie das Zertifikat funktioniert

Beim ersten Start des Host-Servers wird automatisch ein selbstsigniertes TLS-Zertifikat erstellt. Dieses Zertifikat wird lokal auf dem Server-Rechner gespeichert. Anders als bei Webseiten im Internet gibt es hier keine externe Zertifizierungsstelle — das ist für den Einsatz im lokalen Netzwerk normal und ausreichend.

TLS-Fingerabdruck

Der Server stellt seinen TLS-Fingerabdruck über einen unverschlüsselten HTTP-Endpunkt bereit (/api/v1/tls-fingerprint). Der Assistent zeigt diesen Fingerabdruck an, damit Du ihn bei Bedarf mit dem Server abgleichen kannst. Im normalen Betrieb übernimmt der Client das automatisch.

Zertifikat-Wechsel

Wenn sich der TLS-Fingerabdruck ändert (z. B. nach einer Neuinstallation des Servers oder wenn das Zertifikat neu generiert wurde), zeigt der Client eine Warnung an. In diesem Fall musst Du das neue Zertifikat bestätigen. Das ist eine Sicherheitsmaßnahme — es stellt sicher, dass Du weißt, dass sich die Server-Identität geändert hat.

Allgemeine Tipps

So findest Du die IP-Adresse des Servers

  • Windows: Öffne eine Eingabeaufforderung und gib ipconfig ein. Suche nach der IPv4-Adresse des aktiven Netzwerkadapters.
  • macOS: Öffne Systemeinstellungen → Netzwerk. Die IP-Adresse steht beim aktiven Adapter.
  • Linux: Gib ip addr oder hostname -I im Terminal ein.

Verbindung im selben Netzwerk testen

Bevor Du komplexere Szenarien (VPN, Portweiterleitung) einrichtest, teste die Verbindung immer zuerst im selben lokalen Netzwerk. Das vereinfacht die Fehlersuche erheblich.

Server-Modus im Headless-Betrieb

AGYNAMIX Invoicer kann auch ohne grafische Oberfläche als dedizierter Server gestartet werden. Das ist nützlich, wenn der Server-Rechner kein Display hat. Details dazu findest Du in der Dokumentation.

Software-Versionen synchron halten

Client und Host sollten immer dieselbe Version von AGYNAMIX Invoicer verwenden. Bei Updates aktualisiere am besten beide Seiten gleichzeitig, um Kompatibilitätsprobleme zu vermeiden.

Hinweis: Diese Seite ist eine technische Hilfestellung und beschreibt den Stand der Software zum Zeitpunkt der Veröffentlichung. Bei anhaltenden Problemen kontaktiere den Support.