pagebridge diagnose

Query stored diagnostics for unmatched URLs or live-test a single URL against Sanity. Supports two distinct modes depending on whether --url is provided.

Usage

# Bulk mode — query stored diagnostics (requires database)
pagebridge diagnose --site <url> [options]

# Single-URL mode — live match against Sanity (no database needed)
pagebridge diagnose --site <url> --url <page-url> [options]

bash

Two modes

Mode	When	What it does
Bulk (default)	Without `--url`	Queries stored diagnostics from the database — these are written during each sync. Requires a database connection.
Single-URL	With `--url`	Connects directly to Sanity and runs live URL matching for the specified URL. No database needed — useful for quick debugging without running a full sync first.

Options

Flag	Type	Description
`--site <url>`	string	Required. GSC site URL
`--url <url>`	string	A specific page URL to diagnose live against Sanity (enables single-URL mode)
`--reason <reason>`	string	Filter by unmatch reason: `no_slug_extracted`, `no_matching_document`, or `outside_path_prefix` (bulk mode only)
`--limit <n>`	number	Number of results to show (default: `20`). Validates that the value is a number.
`--json`	boolean	Output results as JSON
`--migrate`	boolean	Run database migrations before querying (bulk mode only)
`--db-url <url>`	string	Override DATABASE_URL environment variable (bulk mode only)
`--sanity-project-id <id>`	string	Override SANITY_PROJECT_ID (single-URL mode, resolved from env when not passed)
`--sanity-dataset <name>`	string	Override SANITY_DATASET (single-URL mode, resolved from env when not passed)
`--sanity-token <token>`	string	Override SANITY_TOKEN (single-URL mode, resolved from env when not passed)
`--site-url <url>`	string	Override SITE_URL (single-URL mode, resolved from env when not passed)

Examples

# View all unmatched URLs from last sync
pagebridge diagnose --site sc-domain:example.com

# Diagnose a specific URL live against Sanity
pagebridge diagnose --site sc-domain:example.com --url https://example.com/blog/my-post

# Filter by reason, increase limit
pagebridge diagnose --site sc-domain:example.com --reason no_matching_document --limit 50

# JSON output
pagebridge diagnose --site sc-domain:example.com --json

bash

Unmatch reasons

Reason	Description
`no_slug_extracted`	The URL path could not be parsed into a slug. This usually means the URL structure does not match the configured `pathPrefix`.
`no_matching_document`	A slug was extracted but no Sanity document has a matching slug value. Check if the document exists and the `slugField` is correct.
`outside_path_prefix`	The URL does not match any of the configured `pathPrefix` values across content types. This is expected for non-content pages like the homepage, category pages, etc.

Diagnostic data

For each unmatched URL, the diagnostic includes:

GSC URL — the full URL as reported by Google Search Console
Extracted slug — what PageBridge extracted from the URL path
Unmatch reason — why the URL could not be matched
Similar slugs — suggestions of Sanity document slugs that are close matches (using Levenshtein distance)
First/Last seen — when this URL first and last appeared in GSC data