Comprehensive troubleshooting guide for common issues and their solutions.

• Installation Issues
• Authentication Problems
• 2FA Issues
• PIN Lock Problems
• Search Not Working
• Social Media Integration
• Bot API Issues
• Message Problems
• Performance Issues
• Database Issues
• Common Error Messages

Error:

ERR_PNPM_UNSUPPORTED_ENGINE Unsupported environment

Solution:

# Enable corepack
corepack enable

# Activate correct pnpm version
corepack prepare [email protected] --activate

# Try installation again
pnpm install

Error:

The engine "node" is incompatible with this module

Solution:

# Check Node version
node --version  # Should be 20.x or higher

# Install correct version using nvm
nvm install 20
nvm use 20

# Or using n
n 20

Error:

Failed to connect to PostgreSQL

Solution:

# Check if Docker is running
docker ps

# Restart nself backend
cd .backend
nself stop
nself start

# Check service status
nself status

# View logs
nself logs postgres
nself logs hasura

Error:

Error: listen EADDRINUSE: address already in use :::3000

Solution:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 pnpm dev

Symptoms:

• Correct password not working
• Unable to login to any account

Solutions:

1. Check if using dev mode:

# In .env.local, ensure dev mode is enabled
NEXT_PUBLIC_USE_DEV_AUTH=true

2. Verify backend is running:

cd .backend
nself status

# Should show:
# ✓ PostgreSQL running
# ✓ Hasura running
# ✓ Auth running

3. Reset dev auth state:

// In browser console
localStorage.clear()
sessionStorage.clear()
location.reload()

Symptoms:

• Logged out frequently
• Session lost on browser refresh

Solutions:

1. Check cookie settings:

// In .env.local
NEXT_PUBLIC_SESSION_LIFETIME=86400  # 24 hours in seconds

2. Verify auth token storage:

// In browser console
console.log(localStorage.getItem('nhost'))
// Should show auth tokens

Symptoms:

• Google/GitHub login fails
• Redirect loop after OAuth consent

Solutions:

1. Verify OAuth credentials:

# In .env.local
NEXT_PUBLIC_NHOST_GOOGLE_CLIENT_ID=your_client_id
NEXT_PUBLIC_NHOST_GOOGLE_CLIENT_SECRET=your_secret

2. Check redirect URLs:

• Must match exactly in OAuth provider settings
• Format: https://your-domain.com/api/auth/callback/google

3. Check Nhost Auth configuration:

cd .backend
nself logs auth
# Look for OAuth-related errors

Symptoms:

• Blank space where QR code should appear
• "Failed to generate QR code" error

Solutions:

1. Check if qrcode library is installed:

pnpm list qrcode
# Should show: [email protected]

2. Verify API endpoint:

# Test endpoint
curl http://localhost:3000/api/auth/2fa/setup \
  -H "Authorization: Bearer YOUR_TOKEN"

3. Check browser console for errors:

// Common issue: CORS error
// Solution: Ensure API route is properly configured

Symptoms:

• Valid TOTP code shows as invalid
• "Invalid verification code" error

Solutions:

1. Check system time synchronization:

# TOTP depends on accurate time
# On macOS
sudo sntp -sS time.apple.com

# On Linux
sudo ntpdate pool.ntp.org

2. Verify authenticator app time:

• Open authenticator app settings
• Ensure "Time correction for codes" is enabled
• Sync time with internet

3. Check code timing window:

// In API route, verify window setting
const isValid = speakeasy.totp.verify({
  secret: userSecret,
  encoding: 'base32',
  token: userCode,
  window: 2, // Allows ±1 time step (30 seconds)
})

Symptoms:

• 2FA device lost
• Backup codes not saved
• Cannot login

Solutions:

1. Use emergency password reset:

# Admin can disable 2FA for user in database
psql -U postgres -d nself_chat
UPDATE nchat_user_2fa_settings
SET enabled = false
WHERE user_id = 'USER_ID';

2. Contact administrator:

• Admin can reset 2FA in admin dashboard
• Navigate to Admin → Users → [User] → Security → Disable 2FA

Symptoms:

• Click "Download" but nothing happens
• Codes displayed but can't save

Solutions:

1. Manually copy codes:

• Select and copy all codes
• Save in password manager

2. Check browser popup blocker:

• Allow popups for your domain
• Try in incognito mode

3. Use print function:

• Click "Print backup codes"
• Save as PDF

Symptoms:

• Cannot remember PIN
• Account locked after attempts

Solutions:

1. Use emergency unlock:

• Click "Forgot PIN?"
• Enter account password
• Set new PIN

2. Admin reset (if emergency unlock fails):

psql -U postgres -d nself_chat
DELETE FROM nchat_user_pin_settings WHERE user_id = 'USER_ID';

Symptoms:

• Touch ID/Face ID prompt doesn't appear
• "Biometric authentication failed" error

Solutions:

1. Check browser support:

// In browser console
if (window.PublicKeyCredential) {
  console.log('WebAuthn supported')
} else {
  console.log('WebAuthn not supported - use Chrome/Safari/Edge')
}

2. Verify HTTPS:

• WebAuthn requires HTTPS (except localhost)
• Check URL starts with https://

3. Re-register biometric:

• Settings → Security → PIN Lock
• Disable biometric unlock
• Enable again to re-register

Symptoms:

• App stays unlocked longer than expected
• Auto-lock setting doesn't save

Solutions:

1. Verify auto-lock timeout:

// In browser console
const settings = JSON.parse(localStorage.getItem('pin_settings'))
console.log('Auto-lock timeout:', settings.autoLockTimeout)

2. Check browser visibility API:

• Auto-lock uses Page Visibility API
• Test by switching tabs

3. Clear and reset:

// In browser console
localStorage.removeItem('pin_settings')
// Re-configure PIN lock in settings

Symptoms:

• Search returns no results for known content
• "Search service unavailable" error

Solutions:

1. Check if MeiliSearch is running:

# Test MeiliSearch endpoint
curl http://localhost:7700/health

# Should return: {"status":"available"}

2. Verify search index exists:

curl http://localhost:7700/indexes \
  -H "Authorization: Bearer YOUR_MASTER_KEY"

# Should show "messages" index

3. Re-index all messages:

# Run indexer script
pnpm run search:reindex

# Or manually via API
curl -X POST http://localhost:3000/api/search/initialize \
  -H "Authorization: Bearer YOUR_TOKEN"

Symptoms:

• from:@user doesn't filter
• in:#channel returns wrong results

Solutions:

1. Check query parser:

// Test in browser console
const query = 'from:@john has:file test message'
console.log('Parsed:', parseSearchQuery(query))

2. Verify filter syntax:

// Correct
from:@john          ✓
in:#general         ✓
has:file            ✓
before:2026-01-30   ✓

// Incorrect
from: @john         ✗ (space after colon)
in: general         ✗ (missing #)
has: files          ✗ (wrong keyword)

Symptoms:

• Search takes > 5 seconds
• Browser becomes unresponsive during search

Solutions:

1. Check MeiliSearch performance:

# View MeiliSearch stats
curl http://localhost:7700/stats \
  -H "Authorization: Bearer YOUR_MASTER_KEY"

2. Optimize index settings:

// Reduce searchable attributes if too many
const indexSettings = {
  searchableAttributes: ['content', 'user.display_name', 'channel.name'],
  filterableAttributes: ['channel_id', 'user_id', 'created_at', 'type'],
}

3. Use pagination:

// Don't load all results at once
const results = await search(query, {
  limit: 20, // Show 20 per page
  offset: page * 20,
})

Symptoms:

• Redirect to Twitter fails
• "OAuth token invalid" error

Solutions:

1. Verify OAuth credentials:

# In .env.local
TWITTER_CLIENT_ID=your_client_id
TWITTER_CLIENT_SECRET=your_client_secret
TWITTER_BEARER_TOKEN=your_bearer_token

2. Check OAuth settings in Twitter Developer Portal:

• App permissions: Read and write
• Callback URL: https://your-domain.com/api/social/twitter/callback
• OAuth 2.0 enabled

3. Test OAuth flow:

# Test auth endpoint
curl http://localhost:3000/api/social/twitter/auth

# Should redirect to Twitter OAuth page

Symptoms:

• Connected account but no posts appear
• "Failed to fetch posts" error

Solutions:

1. Check Instagram Graph API credentials:

# Verify in .env.local
INSTAGRAM_APP_ID=your_app_id
INSTAGRAM_APP_SECRET=your_app_secret

2. Verify Instagram Business Account:

• Instagram account must be Business or Creator
• Must be linked to Facebook Page
• Check Meta Business Suite settings

3. Check API permissions:

• Required: instagram_basic, instagram_content_publish
• Review in Meta App Dashboard

4. Test manual import:

# Trigger manual import
curl -X POST http://localhost:3000/api/social/instagram/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "YOUR_ACCOUNT_ID"}'

Symptoms:

• "Rate limit exceeded" error
• Posts stop importing

Solutions:

1. Check rate limit headers:

// In API response headers
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706659200

2. Implement exponential backoff:

// Wait until rate limit resets
const resetTime = response.headers.get('X-RateLimit-Reset')
const waitTime = resetTime * 1000 - Date.now()
await new Promise((resolve) => setTimeout(resolve, waitTime))

3. Reduce polling frequency:

# In configuration, increase interval
SOCIAL_MEDIA_POLL_INTERVAL=600000  # 10 minutes instead of 5

Symptoms:

• 401 Unauthorized error
• "Invalid bot token" message

Solutions:

1. Verify token format:

// Correct format: nbot_<64 hex characters>
const token = 'nbot_1234567890abcdef...'
console.log('Token length:', token.length) // Should be 69

// Check token exists in database

2. Check token expiration:

psql -U postgres -d nself_chat
SELECT * FROM nchat_bot_tokens WHERE token_hash = 'HASH_OF_TOKEN';
-- Check expires_at column

3. Generate new token:

• Admin → Bots → [Your Bot] → Generate New Token
• Update your application with new token

Symptoms:

• 403 Forbidden
• "Bot lacks permission: messages.send"

Solutions:

1. Check bot permissions:

# View bot permissions
curl -X GET http://localhost:3000/api/bots/permissions \
  -H "Authorization: Bearer YOUR_BOT_TOKEN"

2. Grant permission:

• Admin → Bots → [Your Bot] → Permissions
• Enable required permission
• Save changes

Symptoms:

• Webhook configured but no requests received
• Events not triggering webhook

Solutions:

1. Verify webhook URL is accessible:

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

2. Check webhook logs:

# View webhook delivery logs
psql -U postgres -d nself_chat
SELECT * FROM nchat_bot_webhook_logs
WHERE webhook_id = 'YOUR_WEBHOOK_ID'
ORDER BY created_at DESC
LIMIT 10;

3. Verify signature:

// In your webhook handler
const crypto = require('crypto')

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))
}

Symptoms:

• Message sent but doesn't show in channel
• Other users can't see message

Solutions:

1. Check WebSocket connection:

// In browser console
console.log('WS State:', window._wsConnection?.readyState)
// 0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED

2. Verify message in database:

psql -U postgres -d nself_chat
SELECT * FROM nchat_messages
WHERE id = 'MESSAGE_ID';

3. Check GraphQL subscriptions:

// Re-establish subscription
const subscription = useSubscription(MESSAGE_SUBSCRIPTION, {
  variables: { channelId },
})

Symptoms:

• "(edited)" appears but no history
• Can't view previous versions

Solutions:

1. Verify edit history exists:

psql -U postgres -d nself_chat
SELECT * FROM nchat_edit_history
WHERE message_id = 'MESSAGE_ID';

2. Check permissions:

• Only message author and moderators can view edit history
• Verify user role in database

Symptoms:

• Messages marked unread when they've been read
• Read receipt checkmarks not appearing

Solutions:

1. Check if feature is enabled:

// In app config
const config = useAppConfig()
console.log('Read receipts:', config.features.readReceipts)

2. Verify read receipt tracking:

psql -U postgres -d nself_chat
SELECT * FROM nchat_read_receipts
WHERE message_id = 'MESSAGE_ID'
AND user_id = 'USER_ID';

3. Clear and re-track:

// Mark all channel messages as read
await markChannelAsRead(channelId)

Symptoms:

• UI freezes during typing
• Slow message loading
• High memory usage

Solutions:

1. Enable virtual scrolling:

// In message list component
<VirtualizedMessageList messages={messages} overscan={10} itemSize={80} />

2. Reduce message batch size:

// Load fewer messages initially
const MESSAGES_PER_PAGE = 20 // Instead of 50

3. Check for memory leaks:

// In browser dev tools
// Performance → Memory → Take heap snapshot
// Look for detached DOM nodes

4. Clear local storage:

// In browser console
localStorage.clear()
sessionStorage.clear()
location.reload()

Symptoms:

• Images take long to load
• Page stutters when scrolling past images

Solutions:

1. Enable lazy loading:

<img
  src={imageUrl}
  loading="lazy" // Native lazy loading
  alt="..."
/>

2. Use Next.js Image component:

import Image from 'next/image'
;<Image src={imageUrl} width={800} height={600} quality={75} placeholder="blur" />

3. Optimize images:

# Use WebP format
# Compress images before upload
# Maximum recommended: 1920x1080, < 2MB

Symptoms:

• "Migration failed" error during setup
• Database tables missing

Solutions:

1. Check migration status:

cd .backend
nself db migrate status

2. Rollback and retry:

# Rollback last migration
nself db migrate down 1

# Re-run migrations
nself db migrate up

3. Manual migration:

# Connect to database
psql -U postgres -d nself_chat

# Check which tables exist
\dt nchat_*

# Apply missing migrations manually from .backend/migrations/

Symptoms:

• "Too many clients" error
• Database queries timeout

Solutions:

1. Increase connection pool:

# In .backend/.env
POSTGRES_MAX_CONNECTIONS=100
HASURA_POOL_SIZE=20

2. Close idle connections:

psql -U postgres -d nself_chat
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle'
AND state_change < NOW() - INTERVAL '10 minutes';

3. Restart services:

cd .backend
nself restart postgres
nself restart hasura

Cause: Cannot reach backend API

Solutions:

1. Check backend is running: nself status
2. Verify API URL in .env.local
3. Check firewall/network settings

Cause: Authentication token expired

Solutions:

1. Refresh page to get new token
2. Check token expiration settings
3. Re-login if needed

Cause: Service not running or wrong port

Solutions:

1. Check if service is running
2. Verify port in configuration
3. Check for port conflicts

Cause: Missing dependency

Solutions:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Cause: Server/client render mismatch

Solutions:

1. Clear browser cache
2. Check for browser extensions interfering
3. Disable SSR for problematic component

# Frontend logs
# Check browser console (F12)

# Backend logs
cd .backend
nself logs hasura
nself logs auth
nself logs postgres

# Application logs
pnpm dev  # Check terminal output

# Enable debug mode
DEBUG=* pnpm dev

# Or specific namespace
DEBUG=nself:* pnpm dev

1. GitHub Issues: https://github.com/nself-org/nchat/issues
2. Include:
   • nself-chat version
   • Operating system
   • Browser version
   • Steps to reproduce
   • Error messages/logs
   • Screenshots if applicable

• FAQ
• Operations Runbook
• Installation Guide
• Configuration Guide

Last Updated: January 30, 2026 • Version: 0.3.0

Still having issues? Open an issue on GitHub or ask in Discussions.