Monitor and troubleshoot the service
Check health, capacity, transfers, trusted proxy addresses, and common startup failures.
On this page
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.
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 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 before treating local release as completion everywhere.