Troubleshooting

Common issues and solutions for self-hosted Quackback deployments.

Application Won't Start

"Database connection failed"

Symptoms: Application fails to start with connection errors.

Solutions:

Verify PostgreSQL is running

docker compose ps
# or
systemctl status postgresql

Test connection
```
psql "$DATABASE_URL" -c "SELECT 1"
```

Check connection string format

postgresql://user:password@host:5432/database

For Docker networking
- Use container name, not localhost
- Ensure containers are on same network

"Missing environment variable"

Symptoms: Startup error about missing configuration.

Solutions:

Check required variables

# Must be set:
DATABASE_URL
REDIS_URL
SECRET_KEY
BASE_URL

Verify .env is loaded

docker compose config  # Shows resolved values

Check for typos
- Variable names are case-sensitive
- No spaces around =

"Port already in use"

Symptoms: Bind error on startup.

Solutions:

# Find process using port 3000
lsof -i :3000
 
# Kill it
kill -9 <PID>
 
# Or use different port
PORT=8080 bun run start

Database Issues

"Migration failed"

Symptoms: Database migrations don't complete.

Solutions:

Check migration status
```
bun run db:migrate 2>&1 | head -50
```

Ensure database user has permissions

GRANT ALL PRIVILEGES ON DATABASE quackback TO your_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO your_user;

Reset and retry (development only)
```
bun run db:reset
bun run db:migrate
```

Only use db:reset in development environments. This will delete all data.

"Extension pgvector not found"

Symptoms: Vector-related queries fail.

Solutions:

Install extension
```
CREATE EXTENSION IF NOT EXISTS vector;
```

Use pgvector image for Docker

services:
  postgres:
    image: pgvector/pgvector:pg18

Authentication Problems

Symptoms: Users get logged out immediately or can't stay logged in.

Solutions:

Check BASE_URL
- Must match exact domain users access
- Include protocol: https://feedback.example.com
Check cookies
- Cookies require HTTPS in production
- Verify domain settings
Clear browser data
- Delete cookies for the domain
- Try incognito mode

OTP codes not received

Symptoms: Users don't receive magic link emails.

Solutions:

Check console (development)
- OTP codes print to console if no email configured

In development mode without email configuration, OTP codes are printed to the server console for easy testing.

Verify email configuration

# Check SMTP settings
EMAIL_SMTP_HOST
EMAIL_SMTP_PORT
EMAIL_SMTP_USER
EMAIL_SMTP_PASS

Check spam folder

Test email delivery

# Many SMTP providers have test tools
swaks --to test@example.com --server smtp.example.com

OAuth redirect errors

Symptoms: "Redirect URI mismatch" or similar OAuth errors.

Solutions:

Verify callback URL

https://your-domain.com/api/auth/callback/github

Check for trailing slashes
- Must match exactly in provider settings
Verify client ID/secret
- Re-copy from provider dashboard
- Check for whitespace

Performance Issues

Slow page loads

Symptoms: Pages take several seconds to load.

Solutions:

Check database performance

-- Find slow queries
SELECT query, calls, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

Add database indexes
- Check for missing indexes on filtered columns
Increase resources
- More RAM for PostgreSQL
- More CPU for application

High memory usage

Symptoms: Application or database using excessive memory.

Solutions:

Check for memory leaks
```
# Monitor over time
docker stats
```

Tune PostgreSQL

shared_buffers = 256MB  # ~25% of RAM
work_mem = 16MB

Restart periodically
- Set up health checks and auto-restart

Integration Issues

Slack notifications not sending

Symptoms: Connected but no messages appear.

Solutions:

Check integration status
- Admin → Settings → Integrations → Slack
- Look for error messages
Verify channel access
- App must be invited to private channels
- Channel may have been deleted
Check event mappings
- Ensure events are configured
- Verify correct channel selected
Reconnect integration
- Click "Reconnect"
- Re-authorize in Slack

Webhook deliveries failing

Symptoms: Webhooks show failed status.

Solutions:

Check endpoint availability

curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Verify HTTPS
- Webhooks require HTTPS endpoints
- Check certificate validity
Check response codes
- Endpoint must return 2xx
- 4xx errors don't retry (except 429)

Docker Issues

Container keeps restarting

Symptoms: Container in restart loop.

Solutions:

Check logs
```
docker compose logs app --tail 100
```
Check health
```
docker compose ps
```
Verify environment
```
docker compose config
```

Database volume issues

Symptoms: Data not persisting or permission errors.

Solutions:

Check volume mount

volumes:
  - postgres_data:/var/lib/postgresql

Fix permissions
```
sudo chown -R 999:999 /path/to/volume
```

Out of disk space

Symptoms: Write errors, container failures.

Solutions:

Clean up Docker
```
docker system prune -a
```
Check disk usage
```
df -h
docker system df
```

docker system prune -a removes all unused images, containers, and networks. Use with caution in production.

Getting Help

Collect Diagnostic Info

Before asking for help, gather:

Error messages (exact text)

Logs

docker compose logs app --tail 200 > app-logs.txt

Environment (redact secrets)
Steps to reproduce

Support Channels

Issue Template

Use this template when reporting issues to help maintainers understand and resolve your problem faster.

**Environment**
- Quackback version:
- Deployment method: Docker / Bun
- PostgreSQL version:
- OS:
 
**Problem**
[Describe the issue]
 
**Steps to Reproduce**
1.
2.
3.
 
**Expected Behavior**
[What should happen]
 
**Actual Behavior**
[What actually happens]
 
**Logs**

[Relevant log output]

Next Steps

Docker Deployment - Standard setup
Configuration - All options
Requirements - System requirements