Troubleshooting

License Key Issues

”License key invalid”

Symptoms: Setup wizard rejects your key, or admin dashboard shows “Invalid license.”

Fixes:

1. Check the format. License keys look like PC-XXXX-XXXX-XXXX (dashes, not spaces).
2. Copy carefully. Select the entire key from your welcome email. No leading or trailing spaces.
3. Check your domain. License keys are activated for a specific domain. Make sure you’re accessing Pounce from the domain you registered, not an IP address or localhost.
4. Re-copy from email. The raw key is shown once at signup and in the welcome email. If you lost it, contact support.

”License key already activated”

Symptoms: You’re trying to activate a key on a new domain but it’s already in use.

Fix: Each key can be activated on one domain at a time. Deactivate the old domain first in Settings → License, then activate on the new domain.

---

AI Not Responding

AI auto-reply stopped working

Symptoms: Leads come in but no AI responses are generated.

Fixes:

1. Check your free tier limit. Free tier includes 100 leads/month with AI auto-reply. After 100, AI replies pause but leads still arrive. Check usage in Settings → License.
2. Check your LLM API key. Go to Settings → Agent and verify LLM_API_KEY is set and valid.
3. Check your LLM provider. Make sure LLM_PROVIDER matches your key (e.g., ollama, openai, anthropic).
4. Check logs:

sudo journalctl -u pounce --since "1 hour ago" | grep -i error

AI responses are slow

Symptoms: Leads get responses, but it takes minutes instead of seconds.

Fixes:

1. Check your LLM provider’s status page. Outages happen.
2. Ollama users: Make sure Ollama is running (curl http://localhost:11434/api/tags). Check that your model is pulled.
3. Network latency. If using a cloud LLM from a datacenter, check outbound connectivity.

AI not responding to some emails

Symptoms: Some inbound emails don’t get AI responses.

Fixes:

1. Intent filtering. Pounce filters out marketing emails, newsletters, auto-replies, and spam. These are logged as filtered_out. This is expected behavior — check your logs to confirm.
2. Recipient filter. Only emails sent to your configured sender address (e.g., hello@yourdomain.com) are processed. Emails to other addresses on your domain are ignored.
3. Conversation limit. If the conversation has hit the max AI messages (default: 10), further replies are flagged for human review instead.

---

Form Submission Issues

”Form not found” error

Symptoms: Visitors see an error when submitting a lead form.

Fixes:

1. Check the form slug. The URL must match the slug in your admin dashboard. Example: app.pouncefirst.com/api/f/my-form — my-form must exist in Forms.
2. Check the form is active. Forms can be toggled active/inactive in the admin dashboard.
3. Check your site is active. Inactive sites don’t serve forms.

Form submissions not creating leads

Symptoms: Form appears to submit successfully but no leads appear in the dashboard.

Fixes:

1. Check browser console for errors. Open DevTools → Console. Look for red errors.
2. Check server logs:

sudo journalctl -u pounce --since "10 min ago" | grep "lead"

3. Check database connection. If DATABASE_URL is wrong, writes fail silently.

---

Email Issues

Emails not sending

Symptoms: No lead notification emails, no AI auto-reply emails.

Fixes:

1. Check your Resend API key. Go to Settings → Integrations and verify your email API key is set and valid.
2. Check your sender domain. The EMAIL_FROM address domain must be verified in Resend. Go to resend.com/domains and check DNS records.
3. Check DNS records. Your domain needs SPF, DKIM, and DMARC records configured. Resend provides these during domain setup.
4. Check spam folder. New domains have no sender reputation. Emails often land in spam initially.

Resend inbound not working

Symptoms: Emails sent to your business aren’t showing up as leads.

Fixes:

1. Check inbound route. Verify the route exists in your Resend dashboard under Inbound.
2. Check webhook URL. Must point to https://your-pounce-domain.com/api/webhook/resend.
3. Check recipient address. Only emails to your configured EMAIL_FROM address are processed.
4. Check API key. The Resend API key must have read access to inbound emails.
5. Check server logs:

sudo journalctl -u pounce --since "10 min ago" | grep "resend"

---

Payment Issues

Stripe checkout not loading

Fixes:

1. Check STRIPE_PUBLISHABLE_KEY is set in your environment variables.
2. Check browser console for errors. Stripe.js loads from js.stripe.com — ad blockers can interfere.
3. Try disabling ad blockers. Some ad blockers interfere with Stripe checkout.

Subscription not activating after payment

Fixes:

1. Wait 60 seconds. Stripe webhook delivery can have a slight delay.
2. Check webhook configuration. Make sure STRIPE_WEBHOOK_SECRET is set and the endpoint is configured in your Stripe dashboard.
3. Check server logs:

sudo journalctl -u pounce --since "5 min ago" | grep stripe

4. Contact support with your Stripe receipt email if the issue persists.

---

Server Issues

Port already in use

# Find what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 npm start

Database connection refused

Fixes:

1. Check PostgreSQL is running:

sudo systemctl status postgresql

2. Check DATABASE_URL format:

postgresql://...

3. Test the connection:

psql $DATABASE_URL -c "SELECT 1;"

4. Check pg_hba.conf if using local PostgreSQL. You may need to allow password auth.

SSL certificate errors

Fixes:

1. Check certificate expiry:

sudo certbot certificates

2. Force renewal:

sudo certbot renew --force-renewal

3. Check nginx config points to correct certificate paths.
4. Verify auto-renewal is set up (Let’s Encrypt certs expire every 90 days).

High memory usage

Fixes:

1. Limit Node.js heap: Add --max-old-space-size=512 to your start command on small servers.
2. Reduce concurrency if running multiple instances.
3. Monitor for leaks:

sudo systemctl restart pounce
watch -n 5 "ps aux | grep node"

---

Getting More Help

• Email: hello@pouncefirst.com
• Support page: pouncefirst.com/support

When contacting support, please include:

• Your Pounce version (Settings → About)
• Your server OS and Node.js version
• Relevant log output (sudo journalctl -u pounce --since "1 hour ago")
• Steps you’ve already tried