Troubleshooting

General Debugging

Checking Application Logs

Application logs are your primary source of debugging information.

docker logs documenso

docker compose logs -f documenso

kubectl logs -l app.kubernetes.io/name=documenso -n documenso -f

Filtering Logs

Filter logs to find specific errors:

# Docker - find errors
docker logs documenso 2>&1 | grep -i error

# Docker - find warnings
docker logs documenso 2>&1 | grep -i warn

# Show last 100 lines
docker logs --tail 100 documenso

Health Checks

Documenso exposes a health endpoint to verify the application is running:

curl http://localhost:3000/api/health

A healthy response returns HTTP 200. If the health check fails:

Container Status

Check if containers are running and healthy:

docker ps -a | grep documenso

docker compose ps

kubectl get pods -n documenso -o wide

Environment Variable Verification

Verify environment variables are set correctly inside the container:

docker exec documenso printenv | grep NEXT

docker compose exec documenso printenv | grep NEXT

Application Issues

Container Fails to Start

Symptoms: Container exits immediately or enters a crash loop.

Check the exit code:

docker inspect documenso --format='{{.State.ExitCode}}'

Common causes and solutions:

Application Crashes After Startup

Symptoms: Application starts but crashes during operation.

Check for memory issues:

# Docker
docker stats documenso

# Kubernetes
kubectl top pod -n documenso

Solutions:

Startup Timeout in Kubernetes

Symptoms: Pod marked as unhealthy, enters CrashLoopBackOff.

Cause: Startup probe fails before the application is ready.

Solution: Increase startup probe timeout in your deployment:

startupProbe:
  httpGet:
    path: /api/health
    port: 3000
  failureThreshold: 60
  periodSeconds: 5

This allows up to 5 minutes (60 x 5 seconds) for startup.

Port Conflicts

Symptoms: "Port already in use" error.

Find what's using the port:

# Linux/macOS
lsof -i :3000

# Or using netstat
netstat -tlnp | grep 3000

Solutions:

Database Issues

Connection Refused

Error: connect ECONNREFUSED 127.0.0.1:5432

Causes:

• PostgreSQL not running
• Incorrect host in connection string
• Firewall blocking connection
• Database container not started yet

Solutions:

# Direct PostgreSQL
pg_isready -h localhost -p 5432

# Docker Compose
docker compose ps database

Authentication Failed

Error: password authentication failed for user "documenso"

Causes:

• Incorrect password
• Password contains unescaped special characters
• User does not exist

Solutions:

ALTER USER documenso WITH PASSWORD 'newpassword';

Database Does Not Exist

Error: database "documenso" does not exist

Solution: Create the database:

CREATE DATABASE documenso;
GRANT ALL PRIVILEGES ON DATABASE documenso TO documenso;

Too Many Connections

Error: too many connections for role "documenso"

Causes:

• Connection pool exhausted
• Multiple instances without connection pooling
• Connections not being released

Solutions:

postgresql://user:password@host:5432/documenso?connection_limit=5

Migration Failures

Symptoms: Application fails to start with migration errors.

Check migration status:

SELECT * FROM _prisma_migrations WHERE finished_at IS NULL;

Common causes:

Retry failed migration:

UPDATE _prisma_migrations SET rolled_back_at = NOW() WHERE migration_name = 'failed_migration';

SSL Required

Error: SSL/TLS required

Solution: Add SSL mode to connection string:

postgresql://user:password@host:5432/documenso?sslmode=require

Email Issues

Emails Not Sending

Symptoms: No emails received, no errors in logs.

Diagnostic steps:

docker exec documenso printenv | grep SMTP

# Test connection to SMTP server
telnet smtp.example.com 587

SMTP Connection Timeout

Error: Connection timeout

Causes:

• Incorrect SMTP hostname or port
• Firewall blocking outbound SMTP
• SMTP server unreachable

Solutions:

docker exec documenso nc -zv smtp.example.com 587

SMTP Authentication Failed

Error: Invalid login or authentication failed

Causes:

• Incorrect username or password
• Account requires app-specific password
• Account security restrictions

Solutions:

Emails Going to Spam

Causes:

• Missing SPF record
• Missing DKIM signature
• No DMARC policy
• Poor sender reputation

Solutions:

From Address Not Authorized

Error: Sender address rejected

Cause: The NEXT_PRIVATE_SMTP_FROM_ADDRESS is not authorized to send from your email provider.

Solutions:

Signing Issues

No Certificate Found

Error: No certificate found for local signing

Causes:

• Certificate path not configured
• Certificate file not mounted
• Environment variable not set

Solutions:

docker exec documenso printenv | grep SIGNING

docker exec documenso ls -la /opt/documenso/cert.p12

Certificate Permission Denied

Error: EACCES: permission denied, open '/opt/documenso/cert.p12'

Cause: Application cannot read the certificate file.

Solution: Fix file permissions:

# On host before mounting
sudo chown 1001 certificate.p12
chmod 400 certificate.p12

Invalid Certificate Password

Error: mac verify failure

Cause: Incorrect passphrase for the certificate.

Solutions:

openssl pkcs12 -in certificate.p12 -noout

Failed to Get Private Key

Error: Failed to get private key bags

Cause: Certificate has no password or incompatible encryption.

Solution: Re-create the certificate with a password and compatible encryption:

openssl pkcs12 -export -out certificate.p12 -inkey private.key -in certificate.crt \
    -keypbe PBE-SHA1-3DES \
    -certpbe PBE-SHA1-3DES \
    -macalg sha1

Certificate Expired

Error: Certificate has expired

Solution:

openssl pkcs12 -in certificate.p12 -nokeys | openssl x509 -noout -dates

Base64 Decode Error

Error: Invalid base64 in NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS

Cause: Incorrect base64 encoding or line breaks in the value.

Solution: Encode without line breaks:

# macOS
base64 -i certificate.p12 | tr -d '\n'

# Linux
base64 -w 0 certificate.p12

Storage Issues

S3 Access Denied

Error: Access Denied

Causes:

• Incorrect IAM credentials
• Bucket policy doesn't allow operations
• CORS not configured

Solutions:

{
  "Effect": "Allow",
  "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
  "Resource": "arn:aws:s3:::your-bucket/*"
}

S3 Bucket Not Found

Error: The specified bucket does not exist

Causes:

• Bucket name typo
• Bucket in different region
• Bucket doesn't exist

Solutions:

aws s3 ls s3://your-bucket

Signature Mismatch

Error: SignatureDoesNotMatch

Causes:

• Incorrect secret access key
• Clock skew between server and S3

Solutions:

# Check time
date

# Sync time (Linux)
sudo ntpdate pool.ntp.org

Path-Style Access Required

Error: The bucket you are attempting to access must be addressed using the specified endpoint

Cause: S3-compatible service requires path-style URLs.

Solution: Enable path-style access:

NEXT_PRIVATE_UPLOAD_FORCE_PATH_STYLE=true

File Upload Timeout

Symptoms: Large file uploads fail or timeout.

Causes:

• Upload size exceeds limit
• Network timeout
• Reverse proxy timeout

Solutions:

Performance Issues

Slow Response Times

Diagnostic steps:

docker stats documenso

SELECT query, calls, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

Common causes and solutions:

High Memory Usage

Symptoms: Container OOM killed, slow response times.

Solutions:

# Docker Compose
services:
  documenso:
    deploy:
      resources:
        limits:
          memory: 2G

Database Performance Degradation

Symptoms: Slow queries, timeouts.

Diagnostic queries:

-- Check table sizes
SELECT relname, pg_size_pretty(pg_total_relation_size(relid))
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

-- Find long-running queries
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY duration DESC;

Solutions:

VACUUM ANALYZE;

Slow Document Signing

Symptoms: Document completion takes a long time.

Causes:

• Timestamp server latency
• Large PDF files
• Certificate issues

Solutions:

Network Issues

Cannot Reach Application

Diagnostic steps:

docker ps | grep documenso

netstat -tlnp | grep 3000

curl http://localhost:3000/api/health

Reverse Proxy Issues

Symptoms: 502 Bad Gateway, connection refused through proxy.

Solutions:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

WebSocket Connection Failures

Symptoms: Real-time updates not working.

Solution: Configure reverse proxy for WebSocket support:

location / {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

DNS Resolution Failures

Error: getaddrinfo ENOTFOUND hostname

Causes:

• Incorrect hostname
• DNS not configured in container
• Network isolation

Solutions:

docker exec documenso cat /etc/resolv.conf

Getting Help

Before Asking for Help

Gather this information before seeking support:

docker inspect documenso --format='{{.Config.Image}}'

Community Support

• GitHub Discussions
• Discord: Join the Documenso community Discord
• GitHub Issues: For confirmed bugs, open an issue

Reporting Bugs

When reporting bugs, include:

Security Issues

For security vulnerabilities, do not open a public issue. Contact security@documenso.com directly.

Troubleshooting Checklist

Use this checklist when diagnosing issues:

See Also

• Backups - Backup and restore procedures
• Upgrades - Upgrade procedures
• Database Configuration - Database setup reference
• Email Configuration - Email troubleshooting
• Signing Certificate - Certificate troubleshooting
• Storage Configuration - Storage troubleshooting