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 (ollama pull glm-5.1).
3. Network latency. If using a cloud LLM from a datacenter, check outbound connectivity.

---

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: pounce.yourdomain.com/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 → verify 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.

”Email already in use” error on signup

Fix: You may have already created an account. Try signing in, or use a different email. Contact support if you’ve lost access.

---

Payment Issues

Stripe checkout not loading

Fixes:

1. Check STRIPE_PUBLIC_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://username:password@localhost:5432/pounce

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