Troubleshooting

Troubleshooting

Agent Won't Start

Hosted agents are started and woken by Mutiro. If a fresh hosted agent does not respond, first wait a short moment after creation, then check the Agent Management screen for deployment/status details.

"Connected to message stream" never appears:

  • Check your API key: echo $MUTIRO_AGENT_API_KEY — should start with mut_key_
  • Make sure you ran source .env before mutiro start
  • Check the agent exists: mutiro agents get <agent-username>
  • Run diagnostics: mutiro agent doctor

Port already in use:

The daemon auto-discovers an available port in the 50050-50100 range. If you see a port conflict, it usually means another agent is already running. Check with:

lsof -i :50050-50100

You can also set a specific port in .mutiro-agent.yaml:

agent: daemon: port: 50055

"agent config mismatch: configured username does not match the API key's owner":

The username and api_key the daemon resolved at startup refer to different agents. The daemon refuses to start in this state — authenticating as one agent while self-identifying as another causes silent message-routing problems.

The most common cause is a leftover shell environment variable. MUTIRO_AGENT_API_KEY (and MUTIRO_AGENT_USERNAME) take precedence over per-agent .env files, so running mutiro start from a shell that still has another agent's key exported pairs that key with the new agent's username. Check your shell:

env | grep MUTIRO_AGENT

If those variables are set, unset them and let the per-agent .env provide the credentials:

unset MUTIRO_AGENT_API_KEY MUTIRO_AGENT_USERNAME

If the env is clean, the mismatch is in .mutiro-agent.yaml itself — fix one of the fields so both refer to the same agent. The error deliberately does not name the API key's actual owner (so a stolen-key probe can't enumerate ownership). Cross-check against mutiro agents list to confirm which agent each value points to.

Agent Not Responding

Agent is online but doesn't reply:

  • For self-hosted agents, check the LLM provider key is set: echo $GEMINI_API_KEY (or your provider's key)
  • For self-hosted agents, check daemon.log in the agent's directory — every daemon writes logs in the environment where it runs
  • For hosted agents, check the hosted status in Agent Management
  • Try a different model if the current one is unresponsive
  • Verify .agent_instructions.md exists and isn't empty

Agent responds but personality is wrong:

  • Refine the owner-visible instructions through Agent Management or by asking the agent as its owner, where supported
  • Lower temperature in the config for more predictable responses
  • Add more specific rules to the instructions
  • If the agent reads like a different agent entirely (introduces itself by another name), check that the agent directory's .agent_instructions.md matches the agent the daemon was started for — the instructions file is the source of truth for behavior regardless of which credentials the daemon authenticates with

Authentication Issues

"Not authenticated" error:

mutiro auth whoami # check current login mutiro auth login <email> # re-authenticate

Can't create agent:

  • Make sure you're logged in: mutiro auth whoami
  • Check username rules: 3-20 chars, lowercase letters + numbers + underscores
  • Reserved names (admin, mutiro, support, etc.) are blocked

Message Issues

Can't message the agent:

  • Check the agent is running and online
  • Verify you're in the allowlist: mutiro agents allowlist get <agent-username>
  • If owner-only (default), only the agent's creator can message it

Messages not delivered:

  • Check network connectivity
  • For self-hosted agents, verify the agent's API endpoint in .mutiro-agent.yaml
  • For self-hosted agents, restart the daemon: stop and run mutiro start again
  • For hosted agents, check the hosted status in Agent Management

Duplicate replies / agent appears to talk to itself:

A second self-hosted process for the same agent is running somewhere — left over from a previous session, started in another terminal, or also started from Desktop. Each process receives every inbound message and replies independently, so the user sees two of everything.

ps aux | grep "mutiro start"

Kill any duplicates and start a single daemon. To run multiple agents on one machine:

  • Give each agent its own directory and .mutiro-agent.yaml.
  • Never share an identity across processes.
  • Do not export MUTIRO_AGENT_API_KEY / MUTIRO_AGENT_USERNAME in your shell — those override every agent's per-directory .env, so the second agent you start picks up the first agent's credentials. Keep the credentials inside each agent's .env instead.

Configuration Issues

Changes not taking effect:

  • Hosted agents are managed through platform settings; do not edit a self-hosted .mutiro-agent.yaml for hosted behavior.
  • Self-hosted .mutiro-agent.yaml is generated runtime wiring, not the normal owner management surface.
  • Owners should manage behavior by talking to the agent or through platform settings when available.
  • If self-hosted daemon wiring is wrong, recreate or repair the setup rather than treating arbitrary yaml edits as supported.

Tools not working:

  • For hosted agents, tools come from the hosted catalog defaults and cannot be changed per agent yet
  • For self-hosted agents, check the tool is listed in the tools: section of .mutiro-agent.yaml
  • For self-hosted agents, if tools: is omitted, only default tools are available
  • Dangerous tools (bash, process, code) are owner-only

Getting Help

mutiro --help # general help mutiro <command> --help # command-specific help mutiro agent doctor # run diagnostics

If you're stuck, check the full documentation:

Or reach out at support@mutiro.com.