Skip to content

Troubleshooting

Error Codes, Diagnostics, and Resolution Guide

Document Version: 1.0.0
Last Updated: 2026-02-10

1. Error Code Reference

HTTP 400 — Bad Request

Error Code Description Resolution
VALIDATION_ERROR Request body validation failed Check required fields and data types in the API documentation
INVALID_FORMAT Invalid data format (e.g., PEM, date) Verify the format matches the expected specification
DUPLICATE_NAME Resource name already exists in project Use a unique name or update the existing resource

HTTP 401 — Unauthorized

Error Code Description Resolution
AUTH_REQUIRED No authentication token provided Include Authorization: Bearer <token> header
AUTH_EXPIRED Token has expired Re-authenticate to obtain a new token
AUTH_INVALID Token is malformed or tampered with Verify token format; re-authenticate if needed
MFA_REQUIRED Multi-factor authentication required Complete MFA verification

HTTP 403 — Forbidden

Error Code Description Resolution
PERMISSION_DENIED User lacks required permission Contact your administrator to adjust RBAC roles
CSRF_INVALID CSRF token missing or invalid Ensure CSRF token cookie is present; clear browser cache
LICENSE_FEATURE Feature not available in current license tier Upgrade license tier or contact MazeVault support
IP_BLOCKED Request from blocked IP address Contact your administrator

HTTP 404 — Not Found

Error Code Description Resolution
RESOURCE_NOT_FOUND Requested resource does not exist Verify the resource ID; check project scope
PROJECT_NOT_FOUND Project does not exist or user has no access Verify project ID and user's project membership

HTTP 409 — Conflict

Error Code Description Resolution
RESOURCE_CONFLICT Resource already exists Use a different name or update the existing resource
VERSION_CONFLICT Concurrent modification detected Refresh and retry the operation
SYNC_CONFLICT Multi-DC sync conflict Review conflicts in the Sync dashboard; choose resolution strategy

HTTP 429 — Too Many Requests

Error Code Description Resolution
RATE_LIMITED Rate limit exceeded Wait for the window to reset (check X-RateLimit-Reset header)

HTTP 500 — Internal Server Error

Error Code Description Resolution
INTERNAL_ERROR Unexpected server error Check server logs; contact support if persistent
DATABASE_ERROR Database operation failed Verify database connectivity; check health endpoint
ENCRYPTION_ERROR Encryption/decryption failed Verify master key configuration; check key rotation status

2. Common Issues

Login Fails with 403

Symptoms: User receives 403 Forbidden when attempting to log in.

Possible Causes:

  1. CSRF token mismatch — Clear browser cookies and try again
  2. CORS origin not allowed — Verify the application URL matches the configured CORS origins
  3. Account locked — Too many failed attempts; contact administrator
  4. IP restriction — Check if IP allowlisting is configured

Resolution:

# 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

Agent Registration Fails

Symptoms: Agent registration returns an error.

Possible Causes:

  1. Bootstrap token expired — Generate a new bootstrap token
  2. Bootstrap token usage limit reached — Generate a new token with higher limit
  3. Network connectivity — Verify the agent can reach the MazeVault server on port 443
  4. TLS certificate validation — Ensure the agent trusts the server's TLS certificate

Resolution:

# 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

Certificate Import Fails

Symptoms: Certificate import returns a validation error.

Possible Causes:

  1. Invalid PEM format — Ensure the certificate is properly PEM-encoded
  2. Private key mismatch — The private key does not match the certificate's public key
  3. Expired certificate — The certificate has already expired
  4. Chain incomplete — Include the full CA chain

Resolution:

# 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

OCSP Errors

Symptoms: OCSP requests return errors or "Unknown" status.

Possible Causes:

  1. OCSP Responder not running — Check OCSP health endpoint
  2. CA certificate mismatch — Ensure the OCSP responder has the correct CA signing key
  3. Certificate not found — The certificate was not issued by a MazeVault CA

Resolution:

# 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

Database Connection Errors

Symptoms: Health endpoint reports database as unhealthy; API returns 500 errors.

Possible Causes:

  1. Database server unreachable — Network or firewall issue
  2. Authentication failed — Credentials changed or expired
  3. Connection pool exhausted — Too many concurrent connections
  4. SSL/TLS issue — Database SSL configuration changed

Resolution:

# 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

Email Report Fails with Certificate Error

Symptoms: Triggering a weekly expiry report returns an error containing x509: certificate signed by unknown authority. The UI shows "Failed to send report".

Cause: The SMTP server uses a TLS certificate signed by a private or corporate CA that is not in the MazeVault backend container's system trust store.

Resolution:

  1. Obtain the root CA certificate (PEM format) that signed your SMTP server's certificate.
  2. Mount it into the backend container and run update-ca-certificates — see TLS Configuration § 8 for step-by-step instructions.
  3. Verify from inside the container: 
    docker exec mazevault-backend openssl s_client -connect <smtp-host>:587 -starttls smtp < /dev/null 2>&1 | grep 'Verify return code'
    Expect Verify return code: 0 (ok).

3. Diagnostic Commands

Quick Health Check

# 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 .

Log Analysis

# 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"'

Network Diagnostics

# 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. Support Escalation

If the issue cannot be resolved with the above steps:

  1. Collect diagnostics:
  2. Health endpoint output (/api/v1/health/system)
  3. Error messages (exact error code and message)
  4. Application logs (last 1 hour with errors)
  5. Steps to reproduce

  6. Deployment type (AKS / on-premise) and version

  7. Contact support:

  8. Email: info@mazevault.com
  9. Include the diagnostic data above
  10. Reference your license key for priority routing