Skip to main content

Debugging & Troubleshooting

This guide covers common issues and their solutions when deploying and running the Zynomi platform.

Common Issues​

Authentication Issues​

Problem: Users cannot log in​

Symptoms:

  • Login fails with "Invalid credentials"
  • Session expires immediately

Solutions:

  1. Verify Supabase configuration:
# Check environment variables
echo $NEXT_PUBLIC_SUPABASE_URL
echo $NEXT_PUBLIC_SUPABASE_ANON_KEY

  1. Check Supabase dashboard for authentication logs

  2. Verify RLS policies are correctly configured

Problem: JWT token expired​

Solution:

  • Ensure refresh token flow is implemented
  • Check token expiration settings in Supabase

Database Connection Issues​

Problem: Cannot connect to database​

Symptoms:

  • "Connection refused" errors
  • Timeout on database queries

Solutions:

  1. Verify database URL format:
postgresql://user:password@host:port/database

  1. Check network/firewall settings

  2. Verify Supabase project is active

API Gateway Issues​

Problem: KrakenD returns 502 Bad Gateway​

Solutions:

  1. Check backend service health:
curl https://your-site.frappe.cloud/api/method/ping
  1. Verify KrakenD configuration:
krakend check -c krakend.json
  1. Review KrakenD logs:
fly logs -a your-krakend-app

Deployment Issues​

Problem: Vercel deployment fails​

Solutions:

  1. Check build logs in Vercel dashboard

  2. Verify all environment variables are set

  3. Test build locally:

npm run build

Problem: Docker container won't start​

Solutions:

  1. Check container logs:
docker logs container-name

  1. Verify Dockerfile syntax

  2. Ensure all dependencies are installed

Deploying KrakenD​

This guide walks through deploying KrakenD on Fly.io.

Prerequisites​

  • A Fly.io account
  • Flyctl command-line tool installed
  • KrakenD configuration files ready

Steps​

1. Prepare KrakenD Configuration​

Ensure your KrakenD configuration is ready and the necessary files are in the configs directory.

2. Navigate to KrakenD Directory​

cd krakend

3. Initialize Fly.io Application​

flyctl auth login
flyctl launch

4. Destroy Previous Instance (If needed)​

fly apps destroy krakend

5. Deploy the New Image​

flyctl deploy

Logging and Monitoring​

Enable Debug Logging​

Add to your environment:

DEBUG=true
LOG_LEVEL=debug

View Logs​

Vercel:

vercel logs your-app --follow

Fly.io:

fly logs -a your-app

Docker:

docker logs -f container-name

Health Checks​

API Health Check​

curl https://api.your-domain.com/__health

Database Health Check​

curl https://your-project.supabase.co/rest/v1/ \
  -H "apikey: YOUR_ANON_KEY"

Frappe Health Check​

curl https://your-site.frappe.cloud/api/method/ping

Getting Help​

If you're still experiencing issues:

  1. Check the GitHub Issues
  2. Review the API Reference documentation
  3. Contact support at support@zynomi.com