Troubleshooting

Common issues and how to solve them.

If you need deeper operational guidance, see:

Hook Failures

Hooks Not Firing

If you do not see "Metateam hook firing" messages at session start or end:

  1. Check status: Run `metateam hook`. It should show "Enabled: yes" and indicate installations for your clients.
  2. Re-install: Run `metateam hook enable`.
  3. Verify path: Metateam skips certain paths by default (e.g., `node_modules`, `.git`). Ensure you are working in a standard project directory.

Session Not Uploading

If sessions do not appear in the dashboard (https://metateam.ai) or search results:

  1. Check the logs: Inspect `~/.metateam/log/unified.log` for upload errors.
  2. Verify Auth: Run `metateam account whoami` to verify your current login. If needed, re-authenticate with `metateam account login`.
  3. Manual Upload: If a hook failed to upload a specific session, you can manually upload it by prefix: ```bash $ metateam session upload <SESSION_ID_PREFIX> ``` Or upload all unsaved sessions from a provider: ```bash $ metateam session upload claude ```

Crew & Bridge Issues

Crew Command Hangs

If `metateam crew summon` appears to hang:

  1. Check tmux: Ensure `tmux` is installed and functioning.
  2. Attach to the session: The agent might be waiting for a response or blocked by a tool call. ```bash $ metateam crew attach <name> ```

Bridge Connectivity

If metateam crew message fails to reach a remote host:

  1. Version check: In `metateam v1.0.1`, `metateam crew bridge ...` is unavailable (`bridge` is an unrecognized subcommand).
  2. Current workaround: Use single-machine crew workflows, or verify remote messaging support in your installed version before using bridge-specific runbooks.
  3. If your version includes bridge support: verify the bridge process is running on both machines and that network/firewall rules allow relay traffic.

Knowledge Base Discrepancies

KB Entry Not Injected

If an "important" entry is missing from your agent context:

  1. Verify Pinning: Ensure your directory is pinned to the correct project. Check for a `.metateam.json` file in your directory or run: ```bash $ metateam pin <SLUG> ```
  2. Check Importance: Verify the entry or its parent compartment is marked as important with `metateam kb` or `metateam kb list --full`.
    • Do not use `metateam kb tree`: on current builds this resolves as a search for `tree`, not a tree-view command.
  3. Session Timing: Context is injected only at SessionStart. New KB changes will not appear in a session that is already running.

Local Search Issues

No Results for Local Files

If `metateam repo search` returns nothing for files you know exist:

  1. Re-index: Your local index might be stale. ```bash $ metateam repo index ```
  2. Check Status: Run `metateam repo status` to see when the last index was built and which paths were included.

See Also