Troubleshooting

Start from the failed proof gate. Do not rotate tokens, delete data, or reinstall everything before identifying which boundary failed.

MCP cannot connect#

1. Pin the runner to @poolstatis/mcp@0.7.0; do not use @latest.
2. Confirm the host has Node.js 22, 23, or 24 and can run pnpm dlx.
3. Check POOLSTATIS_URL and that POOLSTATIS_TOKEN is a pt_ or sk_ token.
4. Restart the MCP host after changing its private configuration.
5. Run list_projects, then get_onboarding_status. A copied config is not connection proof.

An sk_ token can see only its project. A pt_ token can discover projects in its organization. A pk_ key is ingest-only and cannot call MCP queries.

Skills are not discovered#

Confirm each installed folder contains a non-empty SKILL.md. Codex user skills live under ${CODEX_HOME:-$HOME/.codex}/skills; Claude Code project skills live under .claude/skills. Start a new agent turn after installation. Skills teach workflow but do not replace the MCP connection.

Event was sent but no metric moves#

• Inspect the ingest response for accepted, unregistered, and per-element errors.
• Use sample_events with the exact event, project, and environment.
• Confirm the metric is active, its source event and filters match, and the query range includes the accepted timestamp.
• Check clock-skew and ingest warnings. Do not backfill a fake zero when evidence is missing.

Browser analytics shows no visits#

• Confirm the Browser module started in the browser, not during SSR.
• Confirm the integration starts the Browser module on page load.
• Confirm CORS allows the site's exact origin and the pk_ key targets the expected env.
• Only canonical page.viewed events with $browser_context = "1" enter Web analytics.
• country=unknown means the event predates country enrichment or no trusted country source enriched it; it is not a country.

UTM or source is missing#

UTM values are captured once from the landing session and only from the five canonical allowlisted parameters. Direct visits legitimately report direct/unknown. The SDK never stores the full query string or retroactively copies a later campaign into an existing session.

Click or scroll map has no page#

The aggregate grid can exist before a screenshot, but a layout-accurate overlay requires the exact surface + route + version + device + env snapshot used by the events. Register a stable release id, capture both desktop and mobile after the deploy, upload the immutable PNG/WebP artifact, then query the same tuple. Poolstatis will not guess a background from a different release.

Time on site or bounce is absent#

Confirm the site runs @poolstatis/sdk@0.4.0 and that stored page.engagement snapshots share the owning $page_view_id. Use get_web_overview, get_session_engagement, and get_page_engagement from @poolstatis/mcp@0.7.0; do not approximate attention with first/last timestamps. Missing terminal evidence is incomplete, not zero or bounce.

Replay setup produces no recording#

Install the exact published replay SDK with pnpm add @poolstatis/sdk@0.4.0, then import the separate @poolstatis/sdk/replay entrypoint. Verify affirmative versioned consent, the exact-host allowlist, registered surface and finite route keys, privacy-policy hash, object-store configuration, and manifest status. Only contiguous, validated recordings with an initial full snapshot become playable. See Session Replay.

Bitrix duplicates page views#

Load one bundle per document. The Browser module already observes History API navigation. Call pageViewed() manually only when custom AJAX changes the canonical screen without updating browser history. Keep the route vocabulary finite and verify one navigation in sample_events.

When escalating, include the project slug, environment, event/metric key, timestamp range, HTTP status/error code, and the relevant onboarding or warning output. Never paste tokens, raw personal data, or full production payloads.