Troubleshooting

If something looks off, SpiderPublish: Show Diagnostic Info is the right first step — it dumps activation state, MCP subprocess status, and the latest auth round-trip into the output channel. Paste that into a support ticket if the issue isn't on this page.

This page covers the common cases.

Show Diagnostic Info

Run from the command palette:

SpiderPublish: Show Diagnostic Info

Output channel (SpiderPublish channel, not the regular VSCode output) will contain something like:

=== SpiderPublish diagnostic ===
extension version:   0.1.1
vscode version:      1.95.x
ide:                 cursor

credentials.json:
  path:              /home/user/.spideriq/credentials.json
  exists:            true
  mode:              0600
  has_access_token:  true
  brand_id:          br_xxxxxxxx (redacted: yes)
  expires_at:        2026-08-01T...

spideriq.json:
  path:              /workspace/spideriq.json
  exists:            true
  project_id:        cli_xxxxxxxx
  project_name:      Acme Corp

mcp subprocess:
  pid:               12345
  status:            connected
  cold_start_ms:     336
  last_call:         get_auth_status (200, 89ms)
  bundled_version:   @spideriq/mcp-publish@1.6.0

last get_auth_status:
  authenticated:     true
  agent_id:          agent_xxxxxxxx
  client_id:         cli_xxxxxxxx
  scopes:            content:* templates:* deploy:*

Token values are always redacted in this output — only shape and freshness are surfaced.

Common issues

"Not signed in" but I have a token

Symptom: Status bar shows ✗ not signed in even though ~/.spideriq/credentials.json exists.

Most common cause: the credentials file's expires_at is in the past. PATs default to 90-day expiry.

Fix:

npx @spideriq/cli auth request --email admin@your-company.com

Wait for the email approval, then run SpiderPublish: Who Am I? in the extension to refresh.

Other causes worth checking:

File mode isn't 0600 (some sync tools change it). chmod 0600 ~/.spideriq/credentials.json to fix.
Multiple shells using different $HOME — check that the path in Show Diagnostic Info matches where your CLI wrote the token.

"MCP subprocess wedged" / commands hang

Symptom: Push, Pull, or Deploy starts and never finishes. Output channel shows the command was issued but no response.

Diagnosis: Run SpiderPublish: Show Diagnostic Info. If mcp subprocess.status is anything other than connected, the child process died or stalled.

Fix: Reload the window — Cmd+Shift+P → Developer: Reload Window. The extension respawns the MCP subprocess on activation.

If it persists after reload:

Check Show Diagnostic Info for bundled_version. It should be @spideriq/mcp-publish@1.6.0 or later (depending on the extension version you installed).
Run npx @spideriq/mcp-publish directly in a terminal — does it exit cleanly? If it crashes, that's the underlying bug.
Open a support ticket with the Show Diagnostic Info output.

"Project not bound" — but I have spideriq.json

Symptom: Status bar shows 📁 not bound despite a spideriq.json file existing in the workspace.

Most common cause: The active editor's file is in a folder where the walk-up doesn't find spideriq.json (it's outside the project tree).

The extension walks UP from the active editor's file, not from the workspace root. If you have:

my-multi-tenant-workspace/
  ├── clients/
  │   ├── acme-corp/
  │   │   ├── spideriq.json     ← Acme's binding
  │   │   └── pages/home.json
  │   └── zenith/
  │       ├── spideriq.json     ← Zenith's binding
  │       └── pages/home.json
  └── README.md

Opening README.md (which is above any spideriq.json) shows 📁 not bound. Opening clients/acme-corp/pages/home.json shows 📁 acme-corp. This is intentional — the same window can host fifty clients without ever pushing to the wrong one.

Fix: Open a file inside the project tree, or use Select Project… to write a spideriq.json at the workspace root if you want a single-tenant setup.

"Broken links found" — but I checked the page manually

Symptom: Pre-push audit modal says "3 broken internal links found" but when you click on the diagnostics, the URLs look fine.

Most common cause: The link points to a draft page (or a page that exists in your local edits but hasn't been pushed yet).

The audit runs server-side — it doesn't know about your local-only edits. A link to /new-pricing is broken from the server's perspective even if you just created pages/new-pricing.json locally.

Fix: Push the prerequisite content first, then re-run audit.

If the link points to a page that is published and the audit still flags it, run SpiderPublish: Audit Internal Links standalone — the manual command clears stale audit diagnostics first, so you'll see a fresh server response.

"Confirm token expired" / "Confirm token consumed" / "Confirm token mismatch"

Symptom: Push fails Phase 3 with one of these errors.

Error	Cause	Fix
expired (410)	The user-review session took longer than the token TTL (typically 7 days). Confirm tokens have an expiry.	Run Push Content again — fresh dry-run produces fresh tokens.
consumed (409)	Token was already used. Most often: you double-clicked Approve in the review panel.	Run Pull Content to resync (the server already applied the change), then check if the change actually landed.
mismatch (403)	The payload at confirm time differs from the dry-run payload. Should not happen in normal use — the snapshot-bound design pairs them via the `Map<recordId, PreviewedRecord>`.	This is a real bug if you didn't manually edit the registry. Capture Show Diagnostic Info + the output channel and open a support ticket.

"Pull says 'changed' for files I didn't edit"

Symptom: After Pull, files show as changed even though you didn't touch them.

Most common cause: Server-normalized fields. The server sometimes reformats JSON keys, recomputes derived fields like published_at, or assigns IDs to new records. The first Pull after a server-side change shows these as changed.

Fix: This is normal. The 3-way merge handles it correctly — your local edits are preserved, and pulling again after the server-normalized values land in the registry will clear the false-positive changed state.

If you want a clean slate: stage the "changed" files, push (no-op since the content matches what the server has), and the registry baseline updates.

Extension uses too much CPU / memory

Symptom: Idle CPU spike or RAM creep after the extension has been running for hours.

Most common cause: File watcher on a very large workspace (thousands of files outside the SpiderPublish tree).

Fix: The extension only watches the SpiderPublish content folders (pages/, posts/, components/, templates/) plus spideriq.json and .spideriq/objects.json. If your workspace has a huge node_modules/ or similar, it shouldn't impact the extension — but VSCode's general file watcher might. Consider adding .vscode/settings.json:

{
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true,
    "**/.next/**": true
  }
}

If the extension itself is the culprit (verify via VSCode's Developer: Show Running Extensions — sort by CPU), reload the window. If it recurs, capture Show Diagnostic Info and report.

"Schemas out of date" / unknown field warnings

Symptom: Push surfaces warnings about unknown fields that you know are valid (e.g. a new block type you just shipped server-side).

Most common cause: The 24h schema cache is stale.

Fix: Run SpiderPublish: Refresh Schemas from Server. The cache re-fetches /content/help, /content/playbook, and /content/variables immediately.

For long-running edit sessions where schemas evolve frequently, drop the cache TTL via the spiderpublish.schemaRefreshHours setting (minimum 1 hour).

Reporting bugs

If you've hit something not covered here:

Run SpiderPublish: Show Diagnostic Info, copy the full output.
Capture the SpiderPublish output channel content from the time the issue happened.
If a command failed, note the exact command name + the file/record involved.
Email admin@spideriq.ai with the above. Token values are auto-redacted in Show Diagnostic Info — but double-check the output-channel content for anything sensitive before sending.

Getting help

Community / public docs: docs.spideriq.ai
Starter kit (open source): github.com/martinshein/SpideriQ-ai
CLI counterpart: npx @spideriq/cli --help

Telemetry

The extension sends minimal telemetry by default (errors-only — crash reports to help us catch regressions). Three settings:

Setting	What's sent
`off`	Nothing. Period.
`errors-only` (default)	Anonymous crash reports — extension version, IDE name + version, error message, stack trace. No content, no project IDs, no tokens, no file paths beyond which command crashed.
`usage`	Adds anonymous usage pings: which commands fire, how often, how long they take. Helps us prioritize roadmap. Still no content / project / token data.

Edit via Cmd+, → search "spiderpublish.telemetry".

Show Diagnostic Info​

Common issues​

"Not signed in" but I have a token​

"MCP subprocess wedged" / commands hang​

"Project not bound" — but I have spideriq.json​

"Broken links found" — but I checked the page manually​

"Confirm token expired" / "Confirm token consumed" / "Confirm token mismatch"​

"Pull says 'changed' for files I didn't edit"​

Extension uses too much CPU / memory​

"Schemas out of date" / unknown field warnings​

Reporting bugs​

Getting help​

Telemetry​