Troubleshooting

This guide helps you diagnose and fix common issues with NFYio. Use the diagnostic commands and log analysis tips below, and know where to get help.

Common Issues

Installation

Containers Not Starting

Symptom: docker compose up fails or containers exit immediately.

Cause	Solution
Port conflict	Check ports 3000, 5432, 6379, 7007, 7010, 8080, 8443, 9333 are free: `lsof -i :3000`
Out of memory	Ensure at least 4GB RAM. Check `docker stats`.
Permission errors	Run with appropriate user or use `--user` in compose
Missing .env	Copy `.env.example` to `.env` and fill required values

# Check port usage
lsof -i :3000
netstat -tulpn | grep 3000

# Check container status
docker compose ps
docker compose logs nfyio-gateway --tail 50

Database Connection Errors

Symptom: Gateway fails with “connection refused” or “password authentication failed”.

Cause	Solution
PostgreSQL not ready	Add `depends_on` with healthcheck; increase startup delay
Wrong credentials	Verify `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` match across services
Wrong host	Use service name (e.g., `postgres`) not `localhost` in Docker

# Test database connection
docker compose exec postgres psql -U nfyio -d nfyio -c "SELECT 1"

# Check gateway logs
docker compose logs nfyio-gateway 2>&1 | grep -i "database\|postgres\|connection"

Connectivity

Cannot Reach API or Storage

Symptom: curl or client requests time out or fail.

Cause	Solution
Firewall	Allow ports 3000 (API), 7007 (storage), 443 (if behind proxy)
Wrong URL	Use `http://localhost:3000` for local; `https://api.yourdomain.com` for prod
CORS	Add your origin to `ALLOWED_ORIGINS` for browser requests
Proxy not forwarding	Set `TRUST_PROXY=true` if behind reverse proxy

# Health check
curl -v http://localhost:3000/health
curl -v http://localhost:7007/health

# From another host
curl -v https://api.yourdomain.com/health

Storage Proxy Fails

Symptom: S3 operations fail with “connection refused” or “backend error”.

Cause	Solution
SeaweedFS not running	`docker compose ps seaweedfs-master seaweedfs-volume`
Wrong master URL	Verify `SEAWEEDFS_MASTER` (e.g., `http://seaweedfs-master:9333`)
Volume disk full	Check disk space on volume nodes

# Check SeaweedFS
curl http://localhost:9333/cluster/status

# Storage proxy logs
docker compose logs nfyio-storage --tail 100

Authentication

401 Unauthorized

Symptom: API returns 401 or “Invalid token”.

Cause	Solution
Missing/invalid API key	Check `Authorization: Bearer <key>` header; verify key in dashboard
Expired JWT	Refresh token or re-login
Wrong Keycloak URL	Verify `KEYCLOAK_URL` and realm

# Test with API key
curl -H "Authorization: Bearer $NFYIO_API_KEY" https://api.yourdomain.com/v1/buckets

403 Forbidden

Symptom: Authenticated but “Insufficient permissions”.

Cause	Solution
Missing scope	API key needs scope (e.g., `read:objects`, `write:buckets`)
Resource ownership	User may not own the bucket/object
RLS policy	Check Row Level Security if using custom policies

See Access Keys and API Authentication.

Storage

Upload Fails (Large Files)

Symptom: Upload fails for files > 100MB.

Cause	Solution
`MAX_UPLOAD_SIZE`	Increase in storage proxy config
Nginx `client_max_body_size`	Set to 5G or higher
Multipart	Use multipart upload for large files

# Check storage proxy config
docker compose exec nfyio-storage env | grep MAX_UPLOAD

Bucket or Object Not Found

Symptom: 404 for bucket or object.

Cause	Solution
Wrong bucket name	Bucket names are case-sensitive
Wrong key/path	Verify object key (no leading slash)
Different region/tenant	Ensure correct API key and endpoint

Agents

Embedding Pipeline Not Working

Symptom: Documents not embedding or RAG returns no results.

Cause	Solution
`EMBEDDINGS_ENABLED=false`	Set to `true`
Missing `OPENAI_API_KEY`	Provide valid key
Network to OpenAI	Verify outbound HTTPS to api.openai.com
Wrong model	Check `OPENAI_EMBEDDING_MODEL` is valid

# Check embedding service
docker compose logs nfyio-agent 2>&1 | grep -i embed

Agent Chat Fails or Times Out

Symptom: Chat request hangs or returns 504.

Cause	Solution
LLM API rate limit	Reduce request rate; check OpenAI/Anthropic status
Large context	Reduce `MAX_CONTEXT_TOKENS` or chunk size
Network	Verify connectivity to LLM provider

Diagnostic Commands

Health Checks

# All services
docker compose ps

# Gateway
curl http://localhost:3000/health

# Storage
curl http://localhost:7007/health

# Agent
curl http://localhost:7010/health

Logs

# All services (last 100 lines)
docker compose logs --tail 100

# Specific service, follow
docker compose logs -f nfyio-gateway

# Since timestamp
docker compose logs --since 2026-03-01T12:00:00 nfyio-gateway

# Errors only
docker compose logs nfyio-gateway 2>&1 | grep -i error

Database

# Connect to PostgreSQL
docker compose exec postgres psql -U nfyio -d nfyio

# Check migrations
\dt

# Check buckets
SELECT id, name, created_at FROM buckets LIMIT 10;

Network

# Test connectivity between containers
docker compose exec nfyio-gateway ping -c 2 postgres
docker compose exec nfyio-gateway curl -s http://redis:6379

# DNS resolution
docker compose exec nfyio-gateway nslookup postgres

Log Analysis

Common Log Patterns

Pattern	Meaning
`ECONNREFUSED`	Service not reachable (wrong host/port or not running)
`ETIMEDOUT`	Network timeout; check firewall or service load
`401` / `Unauthorized`	Auth failure; check API key or JWT
`429`	Rate limit; slow down or upgrade plan
`500` / `InternalError`	Server error; check logs for stack trace

Structured Logs

If using JSON logs:

docker compose logs nfyio-gateway | jq 'select(.level == "error")'

Getting Help

GitHub Issues

For bugs, feature requests, or configuration questions:

Repository: github.com/hilaltechnologic/nfyio
Search existing issues before opening a new one
Include: NFYio version, deployment method (Docker/K8s), relevant logs, and steps to reproduce

Discord

For community support and discussions:

Join the NFYio Discord server (link in repository README)
Use the appropriate channel (#help, #general, etc.)

Support Email

For enterprise support or security issues:

Email: support@nfyio.io (or as specified in your contract)
Security: security@nfyio.io for vulnerability reports

Before Asking for Help

Check this troubleshooting guide
Search GitHub Issues
Gather: version, logs, config (redact secrets), and reproduction steps
Try with minimal config to isolate the issue

Next Steps

Error Handling — API error codes and retry strategies
Installation Guide — Deployment and verification
Configuration Reference — Service config
Environment Variables — Variable reference