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 loaded only when the agent runs metateam start (typically once at session start, as part of the persona's startup sequence). KB changes after that point 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