Troubleshooting

Troubleshooting

Symptom-first diagnostic flows. Most "plugin doesn't work" issues are upstream — Box MCP, OAuth, or one of the Operational Notes quirks.

"Plugin validation failed" when installing

Cause: zip shape doesn't match what Cowork/Code expects. The plugin has been validated against Anthropic's working Cowork plugins shape, but if you built from source, common gotchas:

• File permissions 0700 (need 0644 / 0755) — find . -exec chmod 0644 {} \;
• Per-skill references/ or examples/ subdirectories in the zip — strip them
• README in the zip >18 KB — the plugin ships a slim version
• Non-ASCII characters in SKILL.md frontmatter — convert to ASCII

The release-shipped plugin zip passes Cowork validation. If you're hand-building from source, use scripts/build.sh — it enforces the shape.

"Box MCP not connected"

Run /box-mcp-check. The skill walks you through verifying:

1. Are you on Box's official remote MCP at mcp.box.com? (Required for Box AI tools)
2. Are the OAuth scopes granted? (root_readwrite, ai.readwrite, docgen.readwrite)
3. Is the Box admin integration enabled?

If not on the official MCP, the skill surfaces step-by-step instructions to switch.

403 on /box-init template create

Two possibilities:

A) Stale OAuth token after tier upgrade. Most common cause. The token was scoped to your old plan; tier-upgrade doesn't widen scopes. Disconnect + reconnect the Box MCP.

B) Non-admin user. Custom metadata template creation requires the manage_enterprise_properties scope, typically granted to admins. Have a Box admin create the boxMemory template once (see Schema) or proceed without it (recall falls back to _index.json only).

See Operational Notes Note 2.

403 on /box-ai-recall or /box-ai-extract

OAuth scope ai.readwrite not granted. Run /box-mcp-check to confirm. Disconnect + reconnect Box MCP, ensuring ai.readwrite is checked during OAuth.

402 on Box AI call

You've hit your account's AI Unit cap for this billing period. The plugin auto-falls-back to non-AI paths (local index recall, sparse companions).

To get more units:

• Wait for the next billing period
• Purchase additional units via Box admin (Business / Business Plus)
• Upgrade your plan (Enterprise → Enterprise Plus → Enterprise Advanced for more included units)

See Box AI Units.

/box-recall returns wrong / stale results

1. Run /box-index-rebuild --check to inspect for drift. The command reports:
   • Entries in current index that don't exist in source (deleted)
   • Entries in source missing from current (added)
   • Entries with frontmatter mismatch (modified)
2. If drift is non-trivial: /box-index-rebuild to regenerate
3. If you're querying via Box Search (not the index), expect a 10-min indexing lag. The plugin defaults to _index.json lookup; only the last-resort Box Search path hits the lag.

box-ai-recall returns empty results

Possibilities:

1. Hub indexing warm-up. If you just created a Hub or added items, AI Ask returns empty for ~10 min. Plugin auto-detects and falls through to multi-doc Q&A. See Operational Notes Note 7.
2. Wrong workspace scope. Check --scope= or --team= flags.
3. AI Units exhausted. Should surface as 402; if it returns empty silently, box-mcp-check for transient issues.
4. No matching files. Free-text query genuinely has no matches in the file set you provided.

/box-companion always says "couldn't parse"

Three causes:

1. Personal tier. No Box AI access. Run /box-tier-detect. To get AI Extract, upgrade to Business+ and set ai_extract_enabled: true.
2. ai_extract_enabled: false. Default is off — opt in via workspace config.
3. Format unsupported. CAD (DWG, DXF, RVT), audio, video, encrypted PDFs aren't supported by Box AI Extract. The plugin falls back to sparse companion noting the gap.

Companion shows "stale" but I just regenerated

The binary's current sha256 differs from the companion's stored sha256. Run /box-companion <file_id> to regenerate; old companion auto-supersedes.

If repeatedly stale: someone is uploading new versions of the binary faster than the agent reviews. Use webhooks (Webhooks Patterns) to auto-regenerate on upload.

/box-ai-agent says "AI Studio not available"

AI Studio requires Enterprise Advanced. Lower tiers can't create persistent agents. Use box-ai-recall instead (Business+) for per-call Q&A with ad-hoc prompts.

Workspace shows wrong tier in /box-status

The cached tier in _box-memory.json.tier_detected_at may be old. Run /box-status --refresh-tier or /box-tier-detect --refresh to re-probe.

If your account was upgraded and the plugin still shows the old tier:

• This is likely the stale-OAuth-token symptom. Reconnect Box MCP per Operational Notes Note 2.

Slug collision when writing

The plugin auto-appends -2, -3, etc. If it can't resolve after the suffix-bump retry, run /box-index-rebuild memories/ to clean any drift between source files and the index.

Two Box MCPs connected at once

The plugin uses whichever the agent calls; behavior may be unpredictable. Disable all but the official remote MCP at mcp.box.com.

/box-mcp-check --detail reports if multiple are detected.

Reporting bugs

If none of the above fixes your issue:

1. Capture /box-status --check-indexes output
2. Capture /box-mcp-check --detail output
3. Open an issue at https://github.com/mrdulasolutions/BOX/issues with both outputs + the symptom

For security issues, see the repo's security policy in SECURITY.md.

See also

• Operational Notes — eight Box-side quirks
• Box MCP Setup — full MCP setup walkthrough
• FAQ — common questions