Řešení problémů¶

Chybové kódy, diagnostika a průvodce řešením

Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-02-10

1. Přehled chybových kódů¶

HTTP 400 — Chybný požadavek¶

Chybový kód	Popis	Řešení
`VALIDATION_ERROR`	Validace těla požadavku selhala	Zkontrolujte povinná pole a datové typy v API dokumentaci
`INVALID_FORMAT`	Neplatný formát dat (např. PEM, datum)	Ověřte, že formát odpovídá očekávané specifikaci
`DUPLICATE_NAME`	Název zdroje již v projektu existuje	Použijte jedinečný název nebo aktualizujte existující zdroj

HTTP 401 — Neautorizováno¶

Chybový kód	Popis	Řešení
`AUTH_REQUIRED`	Nebyl poskytnut autentizační token	Přidejte hlavičku `Authorization: Bearer <token>`
`AUTH_EXPIRED`	Token vypršel	Znovu se přihlaste pro získání nového tokenu
`AUTH_INVALID`	Token je poškozený nebo byl pozměněn	Ověřte formát tokenu; v případě potřeby se znovu přihlaste
`MFA_REQUIRED`	Vyžadována vícefaktorová autentizace	Dokončete MFA ověření

HTTP 403 — Přístup odepřen¶

Chybový kód	Popis	Řešení
`PERMISSION_DENIED`	Uživatel nemá požadované oprávnění	Kontaktujte administrátora pro úpravu RBAC rolí
`CSRF_INVALID`	CSRF token chybí nebo je neplatný	Ujistěte se, že je přítomna cookie s CSRF tokenem; vymažte mezipaměť prohlížeče
`LICENSE_FEATURE`	Funkce není dostupná v aktuální licenční úrovni	Upgradujte licenční úroveň nebo kontaktujte podporu MazeVault
`IP_BLOCKED`	Požadavek z blokované IP adresy	Kontaktujte svého administrátora

HTTP 404 — Nenalezeno¶

Chybový kód	Popis	Řešení
`RESOURCE_NOT_FOUND`	Požadovaný zdroj neexistuje	Ověřte ID zdroje; zkontrolujte rozsah projektu
`PROJECT_NOT_FOUND`	Projekt neexistuje nebo k němu uživatel nemá přístup	Ověřte ID projektu a členství uživatele v projektu

HTTP 409 — Konflikt¶

Chybový kód	Popis	Řešení
`RESOURCE_CONFLICT`	Zdroj již existuje	Použijte jiný název nebo aktualizujte existující zdroj
`VERSION_CONFLICT`	Zjištěna souběžná modifikace	Obnovte stránku a operaci opakujte
`SYNC_CONFLICT`	Konflikt synchronizace mezi datovými centry	Zkontrolujte konflikty v panelu synchronizace; zvolte strategii řešení

HTTP 429 — Příliš mnoho požadavků¶

Chybový kód	Popis	Řešení
`RATE_LIMITED`	Překročen limit požadavků	Počkejte na reset okna (zkontrolujte hlavičku `X-RateLimit-Reset`)

HTTP 500 — Interní chyba serveru¶

Chybový kód	Popis	Řešení
`INTERNAL_ERROR`	Neočekávaná chyba serveru	Zkontrolujte logy serveru; kontaktujte podporu pokud problém přetrvává
`DATABASE_ERROR`	Operace s databází selhala	Ověřte dostupnost databáze; zkontrolujte health endpoint
`ENCRYPTION_ERROR`	Šifrování/dešifrování selhalo	Ověřte konfiguraci hlavního klíče; zkontrolujte stav rotace klíčů

2. Časté problémy¶

Přihlášení selhává s chybou 403¶

Příznaky: Uživatel obdrží chybu 403 Forbidden při pokusu o přihlášení.

Možné příčiny:

Neshoda CSRF tokenu — Vymažte cookies prohlížeče a zkuste to znovu
CORS origin není povolen — Ověřte, že URL aplikace odpovídá nakonfigurovaným CORS origins
Účet uzamčen — Příliš mnoho neúspěšných pokusů; kontaktujte administrátora
Omezení IP adresy — Zkontrolujte, zda je nakonfigurován IP allowlisting

Řešení:

# Clear cookies and cache in browser, then retry

# If using API directly, ensure you handle the CSRF flow:
# 1. GET the login page (receives Set-Cookie with CSRF token)
# 2. Include the CSRF token cookie in subsequent POST requests

Registrace agenta selhává¶

Příznaky: Registrace agenta vrací chybu.

Možné příčiny:

Bootstrap token vypršel — Vygenerujte nový bootstrap token
Dosažen limit použití bootstrap tokenu — Vygenerujte nový token s vyšším limitem
Síťové připojení — Ověřte, že agent může dosáhnout MazeVault server na portu 443
Validace TLS certifikátu — Ujistěte se, že agent důvěřuje TLS certifikátu serveru

Řešení:

# Test connectivity
curl -v https://vault.example.com/api/v1/health

# If using self-signed certificates, add the CA certificate:
mazevault-agent register \
  --server https://vault.example.com \
  --bootstrap-token <token> \
  --ca-cert /path/to/ca.crt

Import certifikátu selhává¶

Příznaky: Import certifikátu vrací chybu validace.

Možné příčiny:

Neplatný formát PEM — Ujistěte se, že certifikát je správně zakódován v PEM
Neshoda privátního klíče — Privátní klíč neodpovídá veřejnému klíči certifikátu
Certifikát vypršel — Certifikát již expiroval
Neúplný řetězec — Zahrňte celý řetězec CA

Řešení:

# Verify PEM format
openssl x509 -in cert.pem -noout -text

# Verify key matches certificate
openssl x509 -in cert.pem -noout -modulus | md5sum
openssl rsa -in key.pem -noout -modulus | md5sum
# Both hashes must match

# Verify chain
openssl verify -CAfile ca-chain.pem cert.pem

Chyby OCSP¶

Příznaky: OCSP požadavky vracejí chyby nebo stav "Unknown".

Možné příčiny:

OCSP Responder neběží — Zkontrolujte OCSP health endpoint
Neshoda certifikátu CA — Ujistěte se, že OCSP responder má správný podpisový klíč CA
Certifikát nenalezen — Certifikát nebyl vydán MazeVault CA

Řešení:

# Check OCSP Responder health
curl https://vault.example.com/ocsp/health

# Test OCSP request
openssl ocsp \
  -issuer ca.pem \
  -cert server.pem \
  -url https://vault.example.com/ocsp \
  -text

Chyby připojení k databázi¶

Příznaky: Health endpoint hlásí databázi jako nezdravou; API vrací chyby 500.

Možné příčiny:

Databázový server nedostupný — Problém se sítí nebo firewallem
Autentizace selhala — Přihlašovací údaje byly změněny nebo vypršely
Vyčerpán pool připojení — Příliš mnoho souběžných připojení
Problém s SSL/TLS — Změnila se konfigurace SSL databáze

Řešení:

# On-premise: Check database container
docker compose ps client-postgres
docker compose logs client-postgres --tail=20

# Test database connectivity
docker exec client-postgres pg_isready -U mazevault

# Kubernetes: Check database pod
kubectl get pods -n mazevault -l app=postgres
kubectl logs -n mazevault -l app=postgres --tail=20

Odeslání e-mailového reportu selže s chybou certifikátu¶

Příznaky: Spuštění týdenního reportu expirace vrátí chybu obsahující x509: certificate signed by unknown authority. V UI se zobrazí „Failed to send report".

Příčina: SMTP server používá TLS certifikát podepsaný privátní nebo firemní CA, která není v úložišti důvěryhodných certifikátů backend kontejneru MazeVault.

Řešení:

Získejte kořenový CA certifikát (ve formátu PEM), kterým je podepsán certifikát vašeho SMTP serveru.
Připojte jej do backend kontejneru a spusťte update-ca-certificates — viz Konfigurace TLS § 8 pro podrobný návod.

Ověřte z běžícího kontejneru:

docker exec mazevault-backend openssl s_client -connect <smtp-host>:587 -starttls smtp < /dev/null 2>&1 | grep 'Verify return code'

Očekávaný výstup: Verify return code: 0 (ok).

3. Diagnostické příkazy¶

Rychlá kontrola stavu¶

# Check all component health
curl -sk https://vault.example.com/api/v1/health | jq .

# Detailed system health (requires admin token)
curl -sk -H "Authorization: Bearer <admin-token>" \
  https://vault.example.com/api/v1/health/system | jq .

Analýza logů¶

# On-premise: View backend logs
docker compose logs backend --tail=100 --since 1h

# Filter for errors
docker compose logs backend --since 1h 2>&1 | grep '"level":"error"'

# Kubernetes
kubectl logs -n mazevault deploy/mazevault-backend --tail=100 --since=1h
kubectl logs -n mazevault deploy/mazevault-backend --since=1h | grep '"level":"error"'

Síťová diagnostika¶

# Test API connectivity
curl -v https://vault.example.com/api/v1/health

# Test internal connectivity (on-premise)
docker exec mazevault-backend wget -qO- http://client-postgres:5432 || echo "DB port test"
docker exec mazevault-backend wget -qO- http://client-redis:6379 || echo "Redis port test"

# DNS resolution
nslookup vault.example.com

4. Eskalace na podporu¶

Pokud problém nelze vyřešit pomocí výše uvedených kroků:

Shromážděte diagnostické údaje:
Výstup health endpointu (/api/v1/health/system)
Chybové zprávy (přesný chybový kód a zpráva)
Logy aplikace (poslední 1 hodina s chybami)
Kroky k reprodukci
Typ nasazení (AKS / on-premise) a verze
Kontaktujte podporu:
E-mail: info@mazevault.com
Přiložte diagnostické údaje uvedené výše
Uveďte svůj licenční klíč pro prioritní směrování

Související¶

Kontroly stavu — Health endpointy
Monitoring — Monitoring a upozornění
Často kladené otázky — Často kladené dotazy