Troubleshooting Guide & CSP

If beacons aren't showing up in your dashboard, or you're hitting setup warnings, work through this checklist in order.

Diagnostic checklist

1. Inspect page source

Open your website, right-click, and choose View Page Source. Search (Ctrl+F / Cmd+F) for tracker.js:

Confirm the <script> tag is present inside <head>.
Confirm the site-id query parameter is populated and matches your project.

2. Inspect network requests

Open Developer Tools (F12 or right-click → Inspect).
Switch to the Network tab and refresh the page.
Filter by tracker.js and /api/track:
- tracker.js must return 200 OK.
- /api/track (POST) must return 200 OK or 204 No Content.

3. Review browser console messages

Console Message	Probable Cause	Resolution
`Missing site-id parameter`	Script URL is missing `?site-id=...`	Copy the complete snippet from Project Settings → Tracking Snippet.
`Invalid site-id`	Project was deleted or site-id is mismatched	Verify the project exists in your workspace and update the snippet ID.
`Domain not authorized for tracking`	Hostname doesn't match the configured project domain	Update the project's URL in Project Settings → General to match your domain (e.g. `example.com` or `staging.example.com`).
`Failed to fetch / Connection refused`	Analytics deployment is unreachable	Check your Vercel deployment status and verify `NEXT_PUBLIC_SITE_URL`.
`Blocked by client / ERR_BLOCKED_BY_CLIENT`	Ad-blocker or privacy extension intercepted the request	Whitelist your self-hosted analytics domain in your browser extensions.

Content Security Policy (CSP)

If your site enforces a CSP, allow script downloads and beacon connections to your analytics domain:

http

Content-Security-Policy:
  script-src 'self' https://analytics.yourdomain.com;
  connect-src 'self' https://analytics.yourdomain.com;

Next.js example (`next.config.js`)

javascript

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: "script-src 'self' https://analytics.yourdomain.com; connect-src 'self' https://analytics.yourdomain.com;",
          },
        ],
      },
    ];
  },
};

Database connection issues

Symptom / Error	Probable Cause	Resolution
`Connection terminated unexpectedly`	Max connections exceeded / missing pooler	Switch to a pooled connection string (Neon `-pooler` or Supabase port `6543`).
`relation "projects" does not exist`	Database migrations haven't run	Run `npm run db:migrate` against your `DATABASE_URL`.
`SSL connection is required`	Database server requires SSL	Append `?sslmode=require` to your `DATABASE_URL`.
`ETIMEDOUT / ECONNREFUSED`	Database host is firewalled or unreachable	Verify database credentials and confirm outbound access on port 5432 / 6543.

Still stuck?

Open an issue on the GitHub repository with:

Your deployment platform (e.g. Vercel, Neon, Supabase)
Exact console warnings or server error logs
Web framework (e.g. Next.js App Router, React/Vite, Astro)

Next steps

Connecting Your Website

Review framework integration guides for Next.js, React, Astro, and WordPress.

Database Setup & Pooling

Learn more about connection pooling, Neon, Supabase, and Drizzle ORM.