Skip to main content

Troubleshooting

Credentials Not Working​

tfcode validate
tfcode setup

echo $TF_WORKSPACE_ID
echo $TF_API_KEY
echo $TF_REGION

MCP Tools Not Loading​

  1. Verify credentials with tfcode validate
  2. Check network connectivity to MCP server
  3. Check logs:
grep "mcp.*error" ~/.local/share/tfcode/log/dev.log

Binary Not Found​

npm uninstall -g @toothfairyai/tfcode
npm cache clean --force
npm install -g @toothfairyai/tfcode

Permission Errors​

sudo chown -R $(whoami) ~/.npm-local

Server Won't Start​

Port in use:

tfcode serve --port 4097
tfcode serve --port 0

CORS errors:

tfcode serve --cors http://localhost:3000 --cors https://your-app.com

Plugin Not Loading​

  1. Verify file is in .tfcode/plugins/ or ~/.config/tfcode/plugins/
  2. For npm plugins, check the package name in tfcode.json
  3. Check logs: tfcode --log-level DEBUG

Plugin dependencies not installing — ensure .tfcode/package.json exists with required dependencies.

Model Not Available​

tfcode providers list
tfcode validate
tfcode models --refresh

Computer Use​

Computer use drives the real OS GUI — start with the doctor to find what's missing:

tfcode computer doctor
tfcode computer shot
  • macOS cliclick missing: brew install cliclick
  • macOS permissions: grant Accessibility and Screen Recording to the terminal/app running tfcode in System Settings → Privacy & Security, then restart.
  • Linux tools missing: install xdotool + maim (X11) or ydotool + grim (Wayland).
  • Clicks land in the wrong place: the agent must read coordinates straight off the returned screenshot (no DPI scaling). Raise OPENCODE_COMPUTER_USE_IMAGE_MAX to send larger screenshots.
  • Runaway loop stopped: the per-session action budget (default 100, OPENCODE_COMPUTER_USE_BUDGET) halts loops. Interrupt with Escape and refine the task.
  • Audit trail: tail -f ~/.local/share/tfcode/computer/audit.jsonl

See Computer Use for full details.

Voice​

Voice input and spoken callouts — start with the doctor to find what's missing:

tfcode voice doctor
tfcode voice setup --install
  • macOS sox missing: brew install sox (needed for TUI hands-free capture; web works without it).
  • macOS microphone permission: grant Microphone to the terminal/app running tfcode in System Settings → Privacy & Security. tfcode voice setup re-probes.
  • Linux tools missing: sudo apt install sox ffmpeg.
  • Transcription fails: check the browser mic permission and your workspace API access (profile / TF_API_KEY).
  • Slow first transcription: one-time server-side cold start (up to ~20s); warm requests are sub-second.
  • Auto-send fired mid-thought or too eagerly: Settings → Voice → Auto-send — turn it off to review transcripts before sending, or keep talking during the silence buffer to cancel a pending send.

See Voice for full details.

Logging​

tail -f ~/.local/share/tfcode/log/dev.log
tfcode --log-level DEBUG