Troubleshooting: When Your AI Agent Doesn't Work

1. "OpenCode won't start"

This is the most common issue for people just getting started. There are three main causes.

Node.js not installed or wrong version

What this looks like

How to fix it

First, check if Node.js is installed and what version you have:

node --version

You need Node.js 18 or higher. If it's missing or outdated, install it:

# Install with Homebrew (recommended)
brew install node

# Or use the official installer:
# https://nodejs.org/en/download

# Verify it works
node --version   # should show v18+ or v20+
npm --version

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Fedora
sudo dnf install nodejs

# Verify it works
node --version   # should show v18+ or v20+
npm --version

# Download the installer from:
# https://nodejs.org/en/download

# Or use winget:
winget install OpenJS.NodeJS.LTS

# Verify it works (restart terminal first)
node --version
npm --version

Then install OpenCode:

npm install -g opencode

Permission errors

What this looks like

How to fix it

This means npm is trying to install globally in a directory your user doesn't own. There are two fixes:

Option A: Fix npm permissions (recommended)

# Create a directory for global packages
mkdir -p ~/.npm-global

# Tell npm to use it
npm config set prefix '~/.npm-global'

# Add it to your PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Now install again
npm install -g opencode

Option B: Use sudo (quick fix, not ideal)

sudo npm install -g opencode

Command not found

What this looks like

How to fix it

The install worked, but your terminal can't find the opencode binary. Check where npm installed it:

# Find where npm puts global packages
npm bin -g

Make sure that directory is in your PATH:

# Add npm global bin to your PATH
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or for zsh (Mac default):
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
opencode --version

2. "I'm getting rate limited"

What this looks like

What rate limits mean

Free models have usage limits to prevent abuse. The exact limits depend on your provider:

How to check if you're rate limited

Look for these signs:

• You see a 429 error code in the terminal
• Responses suddenly stop working after several successful ones
• The error message mentions "rate limit" or "quota"

If you're using OpenRouter, check your usage dashboard:

https://openrouter.ai/activity

How to fix it

Option 1: Wait it out

Per-minute limits reset in 60 seconds. Daily limits reset at midnight UTC. Just take a break and come back.

Option 2: Switch to a different free model

Each model has its own rate limit. If one model is maxed out, switch to another:

# In OpenCode, switch models with:
/model

# Pick a different free model from the list

See our Best Free Models guide for which models to try.

Option 3: Add $10 to OpenRouter (best fix)

Adding just $10 in credits to OpenRouter dramatically increases your rate limits — from ~50/day to ~1000/day on free models. You won't spend the $10 on free models; it just unlocks higher limits.

1. Go to openrouter.ai/credits
2. Add $10 in credits
3. Keep using the same :free models — your limits are now 20x higher

3. "The model gives bad responses"

What this looks like

How to fix it

Fix 1: Try a different free model

Not all free models are equal. Some are great at code, others at writing, and some are just not very good. If you're getting bad results, switch models before anything else.

Check our Best Free Models guide for recommendations, or try these top picks:

• Best for code: qwen/qwen-2.5-coder-32b-instruct:free
• Best all-around: google/gemini-2.0-flash-exp:free
• Best for writing: meta-llama/llama-3.3-70b-instruct:free

Fix 2: Be more specific in your prompts

Vague prompts get vague results. Compare:

Good prompts include:

• The specific file and function name
• What's happening now vs. what should happen
• Any error messages you see
• Constraints (e.g., "don't change other files")

Fix 3: Add an AGENTS.md file

An AGENTS.md file gives your AI agent permanent context about your project. Create it in your project root:

# AGENTS.md

## Project
- This is a Node.js Express app for managing recipes
- We use TypeScript, Prisma for the database, and Jest for tests

## Conventions
- Use camelCase for variables, PascalCase for types
- All API routes go in src/routes/
- All database queries go in src/services/

## Important
- Never modify the database schema without asking first
- Always write tests for new functions
- The .env file has real credentials — never read or modify it

Save this as AGENTS.md in your project root. OpenCode reads it automatically every time you start a session.

4. "OpenCode can't find my files"

What this looks like

How to fix it

Fix 1: Make sure you're in the right directory

OpenCode works from whatever directory you launched it in. If you started it from your home folder, it can't see files in your project folder.

# Check where you are right now
pwd

# Navigate to your project first, THEN start OpenCode
cd ~/my-project
opencode

Fix 2: Check file permissions

If the file exists but OpenCode can't read it, you may have a permissions issue:

# Check permissions on the file
ls -la src/index.js

# If you see something like ----------, fix it:
chmod 644 src/index.js

# Fix permissions for a whole directory
chmod -R 755 src/

Fix 3: Check the exact file name

File names are case-sensitive on Linux. Index.js is not the same as index.js.

# List files to see exact names
ls -la src/

# Or search for a file by partial name
find . -name "*index*" -type f

5. "My API key doesn't work"

What this looks like

How to fix it

Fix 1: Check the key format

OpenRouter API keys start with sk-or-v1-. If yours looks different, something's wrong.

# A valid OpenRouter key looks like this:
sk-or-v1-abc123def456...

# If yours starts with "sk-" (no "or-v1"), that's an OpenAI key, not OpenRouter.
# Get your OpenRouter key at: https://openrouter.ai/keys

Fix 2: Check the config file

If you set your key in a config file, make sure it's in the right place and properly formatted:

# Check if the config file exists
cat ~/.config/opencode/config.json

The config file should look like this:

{
  "provider": "openrouter",
  "model": "google/gemini-2.0-flash-exp:free",
  "apiKey": "sk-or-v1-your-actual-key-here"
}

Common config file mistakes:

• Extra spaces or quotes around the key
• Missing comma after a field
• Using the wrong field name (apiKey not api_key)

Fix 3: Try the environment variable method

If the config file isn't working, use an environment variable instead. This is often more reliable:

# Set the key for this terminal session
export OPENROUTER_API_KEY="sk-or-v1-your-actual-key-here"

# Make it permanent (add to shell profile)
echo 'export OPENROUTER_API_KEY="sk-or-v1-your-actual-key-here"' >> ~/.bashrc
source ~/.bashrc

# For zsh (Mac default):
echo 'export OPENROUTER_API_KEY="sk-or-v1-your-actual-key-here"' >> ~/.zshrc
source ~/.zshrc

# Verify it's set
echo $OPENROUTER_API_KEY

# PowerShell — set for this session
$env:OPENROUTER_API_KEY = "sk-or-v1-your-actual-key-here"

# PowerShell — set permanently
[System.Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-v1-your-actual-key-here", "User")

# Restart your terminal, then verify
echo $env:OPENROUTER_API_KEY

6. "Obsidian AI plugin not working"

What this looks like

How to fix it

Fix 1: Check your API key in plugin settings

1. Open Obsidian Settings (gear icon)
2. Go to Community Plugins in the left sidebar
3. Find your AI plugin and click the gear icon next to it
4. Check the API Key field — make sure it contains your full key starting with sk-or-v1-
5. Make sure there are no extra spaces before or after the key

Fix 2: Check the model name includes :free

If you're using free models through OpenRouter, the model name must end with :free. Without it, the API tries to use a paid model and fails if you have no credits.

In your plugin settings, find the Model field and make sure it looks like one of these:

google/gemini-2.0-flash-exp:free
meta-llama/llama-3.3-70b-instruct:free
qwen/qwen-2.5-coder-32b-instruct:free

Fix 3: Check the base URL

If your plugin has a "Base URL" or "API Endpoint" field, make sure it points to OpenRouter:

https://openrouter.ai/api/v1

Fix 4: Restart Obsidian

Some plugin settings don't take effect until you restart. Close Obsidian completely and reopen it — not just close the window, but quit the app:

• Mac: Cmd+Q or right-click the dock icon and Quit
• Windows/Linux: File → Quit, or Ctrl+Q

After restarting, test with a simple prompt to confirm it's working.

7. "Still stuck?"

If none of the fixes above solved your problem, here's where to get help.

Search existing issues

Someone has probably hit the same problem before. Check these resources:

• OpenCode GitHub Issues — Search for your error message. If you find a matching issue, check the comments for workarounds.
• OpenRouter Documentation — Covers API keys, rate limits, model availability, and error codes.
• Obsidian Help — For plugin installation and configuration issues.

File a bug report

If your issue is new, file a report on GitHub. Include this information to get a fast response:

**What I did:**
[Step-by-step what you did before the error]

**What I expected:**
[What you thought would happen]

**What happened instead:**
[The actual error — paste the full error message]

**My setup:**
- OS: [Mac/Linux/Windows + version]
- Node.js version: [run `node --version`]
- OpenCode version: [run `opencode --version`]
- Provider: [Zen / OpenRouter / other]
- Model: [which model you were using]

Quick diagnostic commands

Run these and include the output in your bug report:

# System info
node --version
npm --version
opencode --version

# Check if OpenRouter is reachable
curl -s https://openrouter.ai/api/v1/models | head -c 200

# Check your config
cat ~/.config/opencode/config.json 2>/dev/null || echo "No config file found"

# Check environment variable
echo $OPENROUTER_API_KEY | head -c 15