ESC
Type to search across all documentation
↑↓ navigate ↵ open esc close
Troubleshooting

Troubleshooting

"Command not found: logicoal"

The binary isn't in your PATH.

macOS: Check if it's installed at /usr/local/bin/logicoal. If macOS Gatekeeper blocked it:

xattr -d com.apple.quarantine /usr/local/bin/logicoal

Linux: Ensure the binary is in a PATH directory:

sudo mv logicoal /usr/local/bin/
chmod +x /usr/local/bin/logicoal

Windows: Re-run the installer, which adds logicoal to PATH. Restart your terminal after installation.

Login Fails or Browser Doesn't Open

  • Ensure port 9876 is not in use by another application (LogiCoal's OAuth callback runs on this port)
  • Check that the API is reachable: logicoal health
  • A firewall or VPN may be blocking the local callback server. Try disabling temporarily.
  • If the browser doesn't open automatically, check the terminal for the URL and open it manually.

"Credit limit exceeded"

You've used your token allocation. Check your plan:

logicoal status

Options:

  • Wait for your quota to reset (check your plan details on coals.ai)
  • Upgrade your plan at coals.ai

The AI Keeps Asking for Approval

In Normal mode, write operations require your approval. If this is slowing you down:

  • Switch to Auto mode: press Shift+Tab twice or type /mode auto
  • The AI will execute all operations without prompting

You can switch back to Normal mode at any time.

Agents Not Running or Timing Out

  • Default time limit is 5 minutes per agent (odyssey gets 10 minutes)
  • Check agent status: /agents
  • If an agent is stuck, cancel it: /agents kill <id> or /agents kill all
  • For complex multi-step tasks, use the odyssey role — it can delegate to child agents and has a longer time limit
  • In Plan mode, agents with write tools will fail. Switch to Normal or Auto mode.

Agent Keeps Delegating After I Deny It

Denying a delegation checkpoint now immediately stops the parent agent. If an agent still retries after denial, update to the latest version (logicoal update or reinstall). Additionally, denying 3+ checkpoints of any type will stop the agent.

Agent Reads Wrong Files or Ignores My Request

  • The planner role is context-aware: it uses web search for new project questions and reads local files for existing codebase tasks. If it's reading unrelated files, rephrase your request to clarify whether you're asking about a new project or an existing one.
  • The odyssey role plans first before executing. If you want immediate code changes without a planning phase, use @coder directly.

Update Shows Wrong Version

If logicoal update installs a new version but the header still shows the old version number, the binary may not have been rebuilt correctly. Run logicoal update again to re-download. If the issue persists, reinstall from logicoal.ai.

MCP Server Won't Connect

  1. Check the error: /mcp servers
  2. Verify npx is installed and working (most MCP servers use it)
  3. Check required environment variables are set correctly in the config
  4. Try reconnecting: /mcp connect <server-name>
  5. Reload all config: /mcp reload
  6. Test the server directly in your terminal:
    npx -y @modelcontextprotocol/server-github

Custom Command Not Showing Up

  • Commands are loaded at startup. Restart LogiCoal to pick up new files.
  • Verify the file is in ~/.coalcode/commands/ with a .md extension
  • Check the file is readable: open it in a text editor

Custom Role Not Recognized

  • Verify the file is in ~/.coalcode/agents/roles/ (global) or .coals/agents/ (project) with a .md extension
  • The ## System Prompt section is required — roles without it are skipped
  • Restart LogiCoal to reload roles
  • Check with /roles to see if your role appears

/init or .COAL.md Generation Fails

  • Ensure you're authenticated and have credits: logicoal status
  • Large projects may take longer. The command makes multiple AI calls — one for each section.
  • If it fails partway through, run /init --force to regenerate
  • For very large monorepos, try running from a specific subdirectory

Terminal Colors Look Wrong

LogiCoal uses 256-color ANSI sequences.

  • Windows: Use Windows Terminal (not cmd.exe). The classic command prompt has limited color support.
  • Linux: Ensure your terminal emulator supports 256 colors. Most modern terminals (GNOME Terminal, Kitty, Alacritty) do.
  • SSH sessions: Set TERM=xterm-256color before running LogiCoal.

Nothing Happens When I Type

  • Check if a checkpoint approval prompt is active (look for Y/N prompt at the bottom). An agent may be waiting for your approval.
  • Press Escape to cancel any in-progress operation
  • Try Ctrl+C to exit and relaunch

Tool Call Errors or "Too Many Iterations"

The AI is limited to 50 tool iterations per response. If it hits this limit:

  • Rephrase your request to be more specific
  • Break the task into smaller steps
  • Ask the AI to work on one file or component at a time

Getting Help

If you're stuck, type /help in the chat for a summary of all commands and features.

For bugs or feature requests, visit the project repository or contact support through coals.ai.