Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common issues you will encounter when using Murmur, organized by symptom.

​
Setup issues

​
Expired GitHub token

Symptom: murmur setup or murmur login fails with an authentication error. Fix: Re-authenticate with GitHub: 
gh auth login
murmur login
If using a personal access token, regenerate it in GitHub Settings and ensure it has the required scopes (repo, read:org).

​
Missing Claude credentials

Symptom: murmur setup fails with “missing Anthropic API key” or similar. Fix: Ensure your Anthropic API key is available. murmur setup will prompt for it during profile encryption. If you have it set as an environment variable: 
export ANTHROPIC_API_KEY=sk-ant-...
murmur setup

​
API connectivity errors

Symptom: murmur connect or any command fails with “connection refused” or “deadline exceeded.” Fix:
  1. Check your network connectivity and any proxy/VPN settings.
  2. Verify the API address: 
    murmur connect
  3. If using a custom API address, verify it in .murmur/murmur.yaml: 
    api:
  address: api.murmur.example.com:443
  4. Ensure your firewall allows outbound gRPC (port 443).

​
Spawn failures

​
Agent stuck in provisioning

Symptom: After murmur spawn, the agent remains in provisioning phase for several minutes. Causes and fixes:
  1. Pool at capacity — the tenant has hit its max_vms limit. 
    murmur pool status
    If all VMs are in use, either wait for existing agents to finish or increase max_vms in your pool-config.
  2. No warm VMs — min_idle is 0 and a new VM must be created from scratch. 
    murmur get workspace my-workspace
    Consider setting min_idle: 1 or higher for faster startup.
  3. Cloud provider issues — rare, but VM creation can fail due to capacity constraints in the target zone. Check the agent’s status for detailed error messages: 
    murmur status my-agent --timeline

​
Permission denied on spawn

Symptom: murmur spawn returns “permission denied.” Causes and fixes:
  1. Not an org member — verify your GitHub account is a member of the organization.
  2. Missing role — you may need the agent.create permission. Check with: 
    murmur check-permissions agent.create
  3. Wrong tenant — verify you are targeting the correct workspace: 
    murmur whoami

​
Profile encryption errors

Symptom: Spawn fails with “failed to decrypt profile” or “invalid profile.” Fix: Your encrypted profile may be stale or corrupted. Re-run setup: 
murmur setup
This regenerates and re-encrypts your profile. If the problem persists, check that your murmur.local.yaml has not been manually edited.

​
Agent issues

​
No PR opened

Symptom: Agent completed (task-complete phase) but no pull request was created. Causes and fixes:
  1. Check the output configuration — verify the agent was told to create a PR: 
    murmur status my-agent
    Look for out: pr in the configuration. If out was set to push or respond, no PR is expected.
  2. Agent decided not to — review the session to see the agent’s reasoning: 
    murmur session watch my-agent
    The agent may have determined no changes were needed.
  3. Git push failed — the agent may have encountered a push error. Check the session output for Git errors.

​
Agent stuck running

Symptom: Agent has been running for an unusually long time without progress. Fix:
  1. Watch the live session to see what the agent is doing: 
    murmur session watch my-agent
  2. Check if the agent is in a loop (e.g. repeatedly failing a test and retrying): 
    murmur status my-agent --timeline
  3. If the agent is genuinely stuck, you can kill it: 
    murmur kill my-agent

​
Wrong tools or missing dependencies

Symptom: Agent fails because a required tool is not installed (e.g. go: command not found). Causes and fixes:
  1. Check the workspace image — verify the workspace references the correct custom image: 
    murmur get workspace my-workspace
  2. Check startup scripts — if using startup scripts, verify they install the required tools: 
    murmur get environment my-env
  3. Bake a custom image — for tools that take a long time to install, bake them into a custom image. See VM Environment.

​
SSH and connectivity

​
Permission denied on SSH

Symptom: murmur ssh my-agent fails with “permission denied.” Causes and fixes:
  1. Customer placement IAP role — if using a customer placement, your Google Cloud account needs the IAP-Secured Tunnel User role: 
    roles/iap.tunnelResourceAccessor
    Ask your GCP admin to grant this role on the project used by your placement.
  2. SSH keys not configured — verify your SSH keys are in your local overlay: 
    cat .murmur/murmur.local.yaml
    Look for ssh_public_keys. If missing, add your public key and re-run murmur setup.
  3. Agent not running — SSH requires the agent’s VM to be running: 
    murmur status my-agent

​
Attach fails

Symptom: murmur attach my-agent fails to connect. Fix: Verify the agent is in a running or idle phase. Attach connects to the live terminal session, which is only available while the VM is active. 
murmur status my-agent
# Phase must be "running" or "idle"

​
Event delivery

​
Events not reaching agents

Symptom: PR comments or CI results do not trigger agent reactions. Causes and fixes:
  1. install-repo not run — events require the GitHub Actions workflow to be installed: 
    murmur install-repo
    This adds the .github/workflows/murmur.yml workflow to your repo.
  2. Branch pattern mismatch — the event workflow only triggers for branches matching murmur/<developer>/<slug>. Verify the agent’s branch follows this pattern: 
    murmur status my-agent
  3. GitHub App not installed — the Macroscope GitHub App must be installed on the repository. Check your organization’s GitHub App installations.
  4. Workflow disabled — GitHub may have disabled the workflow. Check the Actions tab in your repository.

​
Dashboard issues

​
Cannot sign in

Symptom: GitHub OAuth redirects back to the sign-in page or shows an error. Causes and fixes:
  1. GitHub App not installed — the Macroscope GitHub App must be installed on your GitHub organization. Ask an org admin to install it.
  2. Not an org member — your GitHub account must be a member of the organization that owns the Murmur tenant.
  3. Browser cookies blocked — the dashboard requires cookies. Ensure your browser allows cookies from the dashboard domain.

​
Stale data

Symptom: Dashboard shows outdated agent status or tree. Fix: Hard-refresh the page (Ctrl+Shift+R or Cmd+Shift+R). If the issue persists, the streaming connection may have dropped — navigate away and back to re-establish the stream.

​
Wrong tenant

Symptom: Dashboard shows agents from a different organization. Fix: Use the tenant switcher in the dashboard header to select the correct tenant. Your available tenants are determined by your GitHub org memberships.

​
Pool issues

​
No VMs available

Symptom: Agents are stuck in provisioning, and murmur pool status shows no available VMs. Diagnosis: 
murmur pool status
Causes and fixes:
ConditionFix
Assigned = Max VMsIncrease max_vms in pool-config, or wait for agents to finish
Available = 0, Assigned < MaxVMs are being created; wait a few minutes
Total = 0Run murmur pool ensure to bootstrap the pool

​
Slow agent startup

Symptom: Agents take several minutes to start running. Causes and fixes:
  1. No warm pool — if min_idle is 0, every spawn creates a new VM from scratch: 
    murmur get workspace my-workspace
    Set min_idle: 1 or higher for faster startup.
  2. Large startup script — startup scripts run before the agent starts. If your script takes minutes, consider baking a custom image instead.
  3. Large repo clone — large repositories take longer to clone. Consider using shallow clones or splitting into smaller repos.

​
Diagnostic commands

Use these commands to gather information when troubleshooting:
CommandPurpose
murmur status <slug>Check agent phase, progress, PRs, and cost
murmur status <slug> --timelineView agent timeline events
murmur session watch <slug>Watch live agent session output
murmur pool statusCheck VM pool capacity and availability
murmur connectTest API connectivity
murmur whoamiVerify your identity and tenant
murmur check-permissionsList your effective permissions
murmur versionCheck CLI version (ensure it is up to date)
murmur get workspace <name>Inspect workspace configuration
murmur get environment <name>Inspect environment configuration
murmur lsList your running agents
murmur ls --allList all agents including completed ones
When reporting issues, include the output of murmur version, murmur whoami, and murmur status <slug> --timeline for the affected agent. This information helps diagnose most problems quickly.