---
title: Monitor and troubleshoot the service
label: Monitoring
description: Check health, capacity, transfers, trusted proxy addresses, and common startup failures.
layout: docs
order: 145
---

## Health and logs

`GET /healthz` checks the database, probes receiving storage, and checks that the outbound directory is available. A slow mount can make this endpoint slow. Investigate storage latency as well as the application when health checks fail.

```sh
docker compose logs --since 10m votport
curl --fail http://127.0.0.1:8321/healthz
```

Keep request and delivery URLs out of shared support logs: they contain bearer tokens. Share timestamps, release version, transfer identifiers, and the relevant redacted error instead.

## Metrics

`GET /metrics` exports Prometheus counters, gauges, and histograms. Set `VOTPORT_METRICS_TOKEN`, supply it as a bearer token to the scraper, and restrict scraping to an internal interface.

Monitor active sessions, transfer outcomes, received bytes, free space on each content volume, request errors, and response-header latency. Transfer-duration metrics are separate from HTTP time-to-response-headers; the latter excludes the time spent streaming the body.

Useful transfer outcomes are `published`, `rejected`, `cancelled`, and `interrupted`. Watch rejected and interrupted rates alongside disk capacity and network errors. Native-push refusals distinguish rate limits, invalid capabilities, expiry, and spent capabilities.

## Common failures

| Symptom                                | Check                                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Service refuses to start               | Public HTTPS URL, password length, readable keys, volume ownership, and filesystem probes                                      |
| Every client shares a throttle bucket  | Whether `VOTPORT_TRUSTED_PROXIES` names the proxy's actual socket peer                                                         |
| Receive fails on a share               | Receiving storage qualification, mount identity, server permissions, hard links, stable acknowledgments, and coordinated locks |
| Delivery metadata works but files fail | Matching `/outbound` content, source identity, receipt validation, and staging capacity                                        |
| SSO is unavailable                     | Issuer, callback URL, client ID/secret, provider reachability, and group claims; use local recovery sign-in                    |
| Native transfer cannot connect         | UDP mapping, both firewalls, numeric advertised address where required, and certificate pin                                    |
| Resuming an upload is refused          | Link revocation/expiry, quotas, session idle expiry, and the recorded session profile                                          |

## Retention

`VOTPORT_UPLOAD_RETENTION_DAYS` controls the daily received-file sweep; its default keeps uploaded content. `VOTPORT_AUDIT_RETENTION_DAYS` defaults to 400 days. System settings can override these environment defaults.

A request link's **Legal hold** excludes its uploads from automatic content retention. Explicit file, record, link, and tenant deletion remain separate actions. Backup retention is a separate policy again.

## Ask for help

Provide the release and digest, the time and timezone of the failure, transport, approximate file size, and redacted logs. For managed deployments, [contact your deployment team](/contact/) before changing operational settings.

## Receiving readiness and destination failures

Use **Storage > Receiving storage** to inspect the selected mount, qualification, and failed checks. An unqualified or replaced NAS pauses receiving while administration remains available. Investigate the mount and lock ownership; never remove the writer-lock file to force receiving to resume.

In **Workflows > Deliveries**, inspect each destination independently. A local download link can be released while destination copies are retrying or failed. Route revocation has a separate pending/acknowledged status and persistent retry queue. Check [reception and trade routes](/docs/using/reception/) before treating local release as completion everywhere.