Troubleshooting

Reverse Proxy Configuration

When running behind a reverse proxy (nginx, Apache, etc.), configure ExternalUrlOverride to ensure correct URL generation:

{
  "ExternalUrlOverride": "https://registry.yourdomain.com"
}

Nginx Example

server {
    listen 443 ssl;
    server_name registry.yourdomain.com;

    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        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;
        proxy_cache_bypass $http_upgrade;
        client_max_body_size 0;
    }
}

Common Issues

Container fails to start

• Check logs: docker-compose logs registry
• Verify database connectivity
• Ensure DroneDB library is properly installed

Authentication errors

• Verify Secret is set and consistent
• Check token expiration settings
• Clear browser cookies

File upload failures

• Check MaxRequestBodySize setting
• Verify storage path permissions
• Check available disk space

Build jobs stuck or failing

• Check Hangfire dashboard at /hangfire
• Verify DroneDB library is accessible
• Check disk space and memory

JobIndices table growing too large

• The JobIndices table keeps track of build jobs. A scheduled cleanup task removes old terminal records automatically (default: every night at 4:00 AM, retaining 60 days). If the table has already grown very large, trigger an immediate one-off purge:

  curl -X POST -H "Authorization: Bearer <admin-token>" \
    http://localhost:5000/system/cleanup-jobindices

  You can optionally override the retention period: ?retentionDays=30.
• See JobIndexRetentionDays and JobIndexCleanupCron in the Configuration Reference.

Slow performance

• Consider switching from SQLite to MySQL/MariaDB
• Add Redis cache for high-traffic instances
• Check WorkerThreads configuration

Upgrading: Point clouds (EPT → COPC)

Starting with Registry 2.3.0, point cloud streaming uses the COPC format (build/<hash>/copc/cloud.copc.laz) instead of the legacy EPT layout (build/<hash>/ept/ept.json). Backwards compatibility with old EPT artifacts has been intentionally dropped to keep the build pipeline simple, so any dataset that was built before the upgrade must be migrated before point clouds become viewable again.

You have two options:

1. Run the migration script (recommended). It rebuilds COPC artifacts in place from the existing source LAS/LAZ files, without touching the database. From the DroneDB repository:

   python scripts/migrate-to-copc.py /path/to/registry-data/datasets

   The script requires PDAL on PATH and is idempotent (already-migrated datasets are skipped).

2. Trigger a rebuild of each affected dataset from the Hub UI (Settings → Rebuild) or via the /build API. This regenerates all build artifacts, not only point clouds, and is therefore slower.

After migration, run a one-off cleanup to drop orphaned EPT folders:

curl -X POST -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" -d '{}' \
  http://localhost:5000/system/cleanup

See DatasetCleanupCron in the Configuration Reference for the recurring full-cleanup schedule.

Health Checks

Use the health endpoints to diagnose issues:

# Quick health (basic check)
curl -H "Authorization: Bearer <token>" http://localhost:5000/quickhealth

# Full health (includes database, DroneDB)
curl -H "Authorization: Bearer <token>" http://localhost:5000/health

Health Check Response

The /health endpoint returns detailed status for:

• Database: Connection and query status
• DroneDB: Library availability and version
• Storage: Disk space availability
• Hangfire: Background job processor status

Logs

Log Locations

Deployment	Log Location
Docker	docker-compose logs registry
Native	registry-data/logs/registry.txt

Adjusting Log Verbosity

Change log level in appsettings.json:

"LevelSwitches": {
    "$CONTROL_SWITCH": "Warning"
}

Available levels: Verbose, Debug, Information, Warning, Error, Fatal

Getting Help

If you're still experiencing issues:

1. Check the FAQ
2. Search GitHub Issues
3. Commercial support is available at dronedb.app/contact