Skip to content

Troubleshooting

Jump to bottom
mrdulasolutions edited this page May 25, 2026 · 1 revision

Troubleshooting

Symptom-first diagnostic flows for the on-prem variant. Most "plugin doesn't work" issues are upstream — Box Drive sync, filesystem permissions, or one of the Operational Notes quirks.

If your issue involves Box AI, Box MCP, OAuth, or "tier upgrade," you're on the wrong page — switch to the cloud variant's Troubleshooting. The on-prem variant has none of those surfaces.

"Plugin validation failed" when installing

Same root cause as the cloud variant: zip shape doesn't match what Cowork / Code expects. The on-prem plugin has been validated against Anthropic's knowledge-work-plugins shape and ships passing.

If you built from source, common gotchas:

  • File permissions wrong (need 0644 / 0755) — find . -exec chmod 0644 {} \;
  • Per-skill references/ or examples/ subdirectories in the zip — strip them
  • Non-ASCII characters in SKILL.md frontmatter — convert to ASCII

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

"Box Drive not detected" from /box-drive-detect

Three causes:

  1. Box Drive not running. Open the Box Drive app. On macOS, verify the menu-bar icon is present and shows "connected." Plugin retries on transient errors for up to 30s.
  2. Non-standard mount path. Plugin probes references/box-drive-paths.json. If your mount is elsewhere, populate local_backend.mount_root in your workspace config manually, or symlink to a standard path.
  3. Mount mode is "stream" instead of "mirror." On large libraries, Box Drive may default to streaming. Switch to Mirror mode (Box Drive preferences → Sync → Mirror selected folders) for the workspace folder so files are always local. The plugin will not work against streamed-only files when offline.

See Box Drive Setup for mount mode trade-offs.

"Workspace not writable" from /box-init

Box Drive mounts the Box folder as read-write for the connected user. If box-init fails with EACCES or "not writable":

  1. Verify your OS user owns the path: ls -la <mount-root>.
  2. Verify the Box account connected to Box Drive has edit permission on the target folder. View permissions in Box web UI → folder → "Manage Collaborators."
  3. Verify no parent folder has been set to read-only via Box Shield or Box Governance retention.
  4. Restart Box Drive — sometimes permission caches are stale.

If you're using a shared Box folder, the lowest-permission collaborator sets the floor. A viewer-only collaborator cannot run box-init even if other team members can.

_box-memory.lock is stuck

Symptom: every skill that tries to write reports "lockfile held by , started_at X, renewed_at Y." Force-release should auto-trigger after 30s, but if it doesn't:

  1. Run /box-status --check-lockfile to inspect.
  2. If the lockfile's renewed_at is older than 60s and you're confident no other writer is running: 
    rm <workspace>/_box-memory.lock
    Box Drive will sync the deletion within 30s. Other clients will then see the lock as released.
  3. If you see frequent stale locks, you may have a writer that's crashing without cleanup. Check audit log at <workspace>/.audit/.

For high-contention workspaces, box-index-rebuild --repair-locks sweeps all stale locks in one pass.

.conflict-<timestamp> files appearing

This is Box Drive's signal that two clients wrote the same file before sync converged.

For _index.json.conflict-*: run box-index-rebuild. It auto-merges (union of entries, most-recent updated_at wins).

For memory .md files: no auto-merge. Run box-index-rebuild --check to list. Then either:

  • Delete the .conflict- file if it's a duplicate.
  • Manually merge the diff into the canonical file, then delete .conflict-.

For _box-memory.json.conflict-*: rare but critical. Inspect both versions:

diff _box-memory.json _box-memory.json.conflict-<timestamp>

Reconcile by hand. Delete the .conflict- file. Then run box-index-rebuild --check to verify integrity.

/box-recall returns nothing for a file I just wrote

Three possibilities:

  1. Box Drive hasn't synced yet. If you wrote on machine A and are recalling on machine B, wait 30s for sync. Run /box-status --sync-state to inspect Box Drive sync progress.
  2. Index drift. The write succeeded but the per-folder _index.json didn't update. Run /box-index-rebuild --check to diagnose; /box-index-rebuild to fix.
  3. Slug collision silent fallthrough. Plugin auto-appends -2, -3 on collision; verify the actual saved filename via /box-status --list-recent.

/box-recall returns 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 drift keeps reappearing: someone is writing files outside the plugin (manually in Box web UI, via another tool). The plugin's index can't see those until rebuild. Either consolidate writes through the plugin, or schedule periodic rebuilds.

/box-companion says "couldn't inspect"

The on-prem variant does not use Box AI — it can only inspect what local libraries can read. Default supported types:

  • Plain text: .txt, .md, .csv, .json, .yaml, .toml
  • PDF (text-only via pdftotext if installed)
  • Images (basic EXIF via exiftool if installed)

For everything else (binaries, encrypted files, proprietary formats), the companion is sparse — file size, sha256, mime type, last modified. No content extraction.

If you need full extraction, you're outside the air-gap envelope. Either:

  • Switch to the cloud variant (Box AI Extract handles many formats)
  • Use the hybrid approach: extract on a connected machine, write the companion .md back, then sync to the air-gapped workspace

Companion shows "stale" but I just regenerated

Same as cloud: the binary's current sha256 differs from the companion's stored sha256. Run /box-companion <path> to regenerate.

Common cause: another process is rewriting the binary faster than you regenerate. Inspect mtime: if it keeps advancing, find the writer.

.schema-pin is "out of sync"

CI workflow ci-check-schema-sync.sh failed. Cause: the files under synced/ don't match the cloud repo at the SHA in .schema-pin.

To fix:

  1. Decide which direction is right:
    • Sync forward: the cloud repo has new schema you want. Run scripts/sync-shared-refs.sh <new-sha> to bump .schema-pin and re-pull.
    • Revert local change: the cloud repo is canonical and someone edited synced/ locally by mistake. git checkout synced/ to discard local edits.
  2. Re-run CI.

Never edit synced/ files directly — they exist to be pulled from the cloud repo. Local edits are always wrong.

"I'm seeing outbound network requests during skill execution"

This should never happen by design. The air-gap is structural:

  1. The plugin's .mcp.json declares {"mcpServers": {}} — no MCP servers, no API endpoints.
  2. CI scans all SKILL.md files for forbidden patterns (api.box.com, mcp__, fetch(...box), etc.) and fails the build if any appear.

If you observe outbound traffic:

  1. Verify what's making the call. Use tcpdump, Little Snitch, or your network monitor.
  2. Confirm it's not your agent runtime itself (Claude/Bedrock/Azure) phoning home — that's outside the plugin's control and is governed by your LLM provider configuration. See Supported LLM Configurations.
  3. If it's genuinely the plugin: that's a Layer-2 CI failure (forbidden pattern slipped through). File a security issue immediately at https://github.com/mrdulasolutions/BOX-Onprem/security/advisories/new.

Compliance posture mismatch reported by /box-airgap-status

/box-airgap-status cross-references your workspace's declared compliance_target with the LLM provider you're running against. Common mismatches:

  • Declared HIPAA, no BAA on file: your LLM provider doesn't have a BAA, so even though Box has one, the chain breaks at inference time. Either get a BAA (Anthropic Enterprise + BAA, AWS Bedrock + BAA) or downgrade the declaration.
  • Declared FedRAMP High, LLM is commercial Anthropic: commercial Anthropic API is not FedRAMP. Switch to Azure Government AI Foundry or AWS GovCloud Bedrock.
  • Declared ITAR, LLM provider not US-persons-attested: the inference layer must guarantee US persons. Most commercial APIs do not.

See Supported LLM Configurations for the certified matrix.

Reporting bugs

If none of the above fixes your issue:

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

For security issues, use the private security advisory flow at https://github.com/mrdulasolutions/BOX-Onprem/security/advisories/new. See SECURITY.md in the repo.

See also

box-memory-onprem · MIT · Repo · Latest release · Cloud variant · Cloud wiki

Home

Getting started

Concepts

Compliance

Skills reference

Operations

Project

Clone this wiki locally