Troubleshooting¶

Quick solutions for common issues when running Seer Marketing Agent workflows.

Need help fast?

Jump to Error Code Index for quick lookup by error message.

I Can't Complete My Task¶

"My workflow won't start"¶

Likely cause: Prerequisites missing (plugin not installed, MCP not connected)

Solution: Run /utils:commands to verify installation. See Command Issues below.

"I don't have the data it's asking for"¶

Likely cause: Client not in BigQuery, or missing permissions

Solution: Check client name matches BigQuery org_name. You can also provide data manually when prompted.

"BigQuery/MCP says it's unavailable"¶

Likely cause: Connection timeout or rate limiting

Solution: All workflows gracefully degrade. Answer "no" when asked about data sources and provide data manually.

"Command not recognized"¶

Likely cause: Plugin not installed or namespace issue

Solution: Verify with /utils:commands. Ensure core-dependencies is installed first.

"Output doesn't look right"¶

Likely cause: Missing context or incorrect inputs

Solution: Review the intake questions and provide more specific answers. Check the command's "What you get" section to verify expected outputs.

See also: Relevant workflow page (e.g., SEO Workflows)

Quick Triage¶

Issue Type	Where to Go	Example
Command not found	Command Issues	`/seo-content-audit` not recognized
MCP connection	Seer MCP Connection Issues	"Not connected to Seer MCP"
Data missing	Data & Seer MCP Issues	"No data found for client"
Skill not loading	Skill Activation Issues	"Skill not activated"

Error Code Index¶

Error Message	Category	Quick Fix
"Command not found"	Commands	Run `/utils:commands` to verify installation
"No data found for client"	Data	Check client name matches BigQuery `org_name`
"Not connected to Seer MCP"	Seer MCP	Reconnect via Claude → Manage Connectors
"Query timeout"	Seer MCP	Simplify query, reduce date range
"Rate limit exceeded"	Seer MCP	Wait and retry
"Plugin not loaded"	Commands	Ensure `core-dependencies` is installed
"Skill not activated"	Skills	Check trigger keywords in prompt
"Failed to list skills: 403 Forbidden"	Skill Sync	Use full Cookie header, not just `sessionKey`
"Zip cannot contain nested zip files"	Skill Sync	Remove `.zip` from skill `resources/` — see AGENTS.md §13
"Connector disconnected unexpectedly"	Seer MCP	Reconnect via Manage Connectors after any Google password change
Skills all stop firing at once	Skills	Check status.claude.com for a File Operations outage

Command Issues¶

"Command not found"¶

Symptom	Cause	Solution
`/seo-content-audit` returns error	Plugin not installed	Run `/utils:commands` to check available commands
Command exists but won't run	Core dependencies missing	Install `core-dependencies` plugin first
Works in Claude Code, not OpenCode	Different plugin paths	Check `.opencode/config.json` plugin paths

Verification steps:

Run /utils:commands to see active commands
Verify the plugin is installed: check plugins/divisions/seo/ exists
Restart your session after plugin installation

Plugin not loaded¶

Symptom	Cause	Solution
No commands available	Plugin manifest missing	Verify `.claude-plugin/plugin.json` exists
Some commands missing	Partial installation	Re-install the plugin
Dependency errors	Missing core-dependencies	Install `core-dependencies` first

Seer MCP Connection Issues¶

"Not connected to Seer MCP"¶

Cause	Solution
Not in Seer workspace	Switch to Seer Team Plan in Claude settings
OAuth session expired	Reconnect via Claude → Manage Connectors → SEERMCP
Tools not loaded	Start a new conversation (tools load at conversation start)

"Connector not appearing"¶

Cause	Solution
Page not refreshed	Refresh the browser page
Wrong workspace	Ensure you're in the Seer Team workspace
Cache issue	Try incognito/private browsing mode

"Connector disconnected unexpectedly"¶

Cause	Solution
Google/Gmail password changed	Seer's periodic password rotation silently disconnects Google-based connectors (Drive, Gmail) and anything using one-click Google login. Reconnect via Claude → Manage Connectors after any password update.
Long idle period	OAuth tokens can expire after extended inactivity; reconnect the same way.

"Authorization fails"¶

Cause	Solution
Wrong Google account	Use your @seerinteractive.com account
Permissions not granted	Re-authorize and accept all permissions
Browser blocking popup	Allow popups for claude.ai

"Query timeout"¶

Cause	Solution
Large date range	Reduce to last 30 days
Complex query	Simplify joins, use specific tables
Many rows returned	Add LIMIT clause or filter conditions

"Rate limit exceeded"¶

Wait 60 seconds and retry. For bulk operations, space requests apart.

Data & Seer MCP Issues¶

"No data found for client"¶

Symptom	Cause	Solution
Empty results	Client name mismatch	Use exact `org_name` from BigQuery
Partial data	Date range issue	Verify data exists for requested dates
Access denied	Permissions	Check your Seer MCP role includes this dataset

Finding the right client name:

List the available clients in SeerSignals

Manual fallback: All workflows accept manual data input. The agent will prompt you if Seer MCP is unavailable.

Skill Activation Issues¶

Skill not auto-loading¶

Symptom	Cause	Solution
Writing standards not applied	Missing trigger keywords	Include "deliverable" or "client" in prompt
SEO methods not used	Wrong context	Mention "seo", "rankings", or "serp"
Quality gates skipped	No data keywords	Include "analysis" or "metrics"
No response to slash command or trigger phrase	Skills toggle is off	Enable in Claude.ai: Customize → Skills, toggle top-right

Debug skill activation:

# Check which skills are registered
grep -r "auto-load: true" plugins/*/skills/*/SKILL.md

All skills stopped working at once¶

Cause	Solution
Anthropic-side "File Operations" outage	Skills depend on File Operations; when Anthropic reports elevated errors there, skills silently stop firing site-wide. Check status.claude.com before assuming a local config issue — this resolves on Anthropic's end.

Response Quality Issues¶

Slow responses¶

Workflow	Expected Time	If Longer
`/seo-content-audit`	30-60 min	Check BigQuery query performance
`/seo-search-landscape`	90-120 min	Normal for 12-question analysis
`/content-gap-analysis`	60-90 min	Reduce competitor count

Generic or low-confidence output¶

Symptom	Cause	Solution
Vague recommendations	Insufficient context	Provide specific competitors, challenges
Missing data citations	Data not fetched	Check Seer MCP connection
Overly cautious language	Quality gates working	This is intentional - add evidence for confidence

Improve output quality:

Be specific during Intake phase
Mention unique client challenges
Name specific competitors
Provide target audience details

Installation Issues¶

Claude Code¶

Issue	Solution
Marketplace not found	Run `/plugin marketplace add seerinteractive/agents-infra`
Plugin install fails	Check internet connection, try again
Commands not appearing	Restart Claude Code after installation

OpenCode¶

Issue	Solution
Plugins not auto-discovered	Check `plugins/` directory exists in project root
Config not loading	Verify `.opencode/config.json` syntax
MCP connection failing	Check `~/.claude/.mcp.json` configuration

Skill Sync (Claude.ai Org) Issues¶

These apply to the Sync Skills to Claude.ai GitHub Actions workflow that pushes skills from this repo to a Claude.ai org.

"Failed to list skills: 403 Forbidden"¶

Cause	Solution
`CLAUDE_SESSION_KEY` alone (Cloudflare gate)	Set the full Cookie header via `CLAUDE_COOKIE_HEADER` secret — must include `__cf_bm` + `cf_clearance` + `sessionKey` at minimum
`lastActiveOrg` cookie does not match `CLAUDE_ORG_ID` secret	In the browser, switch to the target org, refresh, then re-export cookies; `lastActiveOrg` must equal the secret's UUID
Cloudflare cookies expired (`__cf_bm` rotates ~30 min)	Capture a fresh cookie dump from a logged-in browser and rotate both GitHub secrets
Account is not org admin	Verify access via Claude.ai → Settings → Organization → Skills (admin-only UI)

"Zip cannot contain nested zip files" (error_code: `zip_nested_zip`)¶

Cause	Solution
A skill committed a `.zip` (or `.tar.gz`) under `resources/`	Remove the archive: `git rm <path>`; per AGENTS.md §13 binary assets including ZIP belong in Google Drive, not git. `scripts/package-skills.sh` strips nested zips automatically but won't auto-commit the removal.

A skill isn't showing up in Claude.ai¶

There's no hard skill-count cap. If a skill is missing:

Check it's registered in the owning plugin's skills[] array in .claude-plugin/marketplace.json — Claude.ai only syncs skills listed there.
Check it's merged to master — Claude.ai's marketplace sync only reads that branch.
Check it's been promoted to the Organization lane rather than left as a Personal/Shared skill — ask an org admin (Settings → Organization → Skills) to confirm.

Workflow run is skipped¶

Cause	Solution
`SKILL_SYNC_ENABLED` repo variable is unset or `false`	`gh variable set SKILL_SYNC_ENABLED --repo <owner>/agents-infra --body true`
Push didn't touch any of the watched paths	Either modify a watched path or use the manual `workflow_dispatch` trigger with `force_all=true`

Workflow ran but uploaded 0 skills¶

Cause	Solution
`git diff HEAD~1 HEAD` found no changed skill dirs	Use `workflow_dispatch` with `force_all=true` to upload everything regardless of diff
`dist/skills/` was empty (packaging failed silently)	Re-run with `--target web` locally and inspect `dist/skills/`; the workflow uses the same flag

Getting Help¶

If these solutions don't resolve your issue:

Slack: #inn-prototype-seer-mcp for Seer MCP issues
Search the docs: Use the search bar to find related topics
Check FAQ: Frequently Asked Questions
File an issue: GitHub Issues

When filing an issue, include:

Command you were running
Exact error message
Whether Seer MCP is connected (check in Manage Connectors)
Steps to reproduce

Quickstart - Installation and setup
Connect to Seer MCP - Setup guide
FAQ - Common questions

Last updated: 2026-01-26