Skip to content

TROUBLESHOOTING-OPENCODE.md

Latest commit

 

History

History
359 lines (268 loc) · 8.8 KB

TROUBLESHOOTING-OPENCODE.md

File metadata and controls

359 lines (268 loc) · 8.8 KB

Open Code CLI Troubleshooting Guide

✅ RESOLVED: Tool Usage Requires Qwen3 Models

Discovery (2025-11-18)

Only Qwen3 models have tool usage capabilities with Open Code CLI!

Root Cause: Tool/function calling requires specific model training. Qwen3 family has built-in function calling capabilities, while Mistral Nemo and Granite models lack this training.

Working models:

  • ✅ qwen3:8b-16k - TESTED & CONFIRMED working
  • ✅ qwen3:8b - Likely works (same family, needs testing)
  • ✅ qwen3:4b - Likely works (same family, needs testing)

Non-working models (analysis only):

  • ❌ granite3.1-moe:latest - Plans but doesn't execute
  • ❌ mistral-nemo:12b-instruct-2407-q4_K_M - Excellent analysis but no file creation

Issue: Models Not Creating Files

Problem

Some Ollama models understand tasks but do not execute file creation commands.

Symptoms:

  • Model generates task descriptions/plans
  • Model shows understanding of the request
  • No actual file is created
  • Terminal shows planning output but no action

This is NOT a bug - it's a model capability limitation!

Diagnostic Steps

Step 1: Verify Open Code CLI Setup

# Check Open Code CLI version
opencode --version

# Verify Ollama is running
curl http://localhost:11434/v1/models

# Check available models
ollama list

Step 2: Test with Different Prompts

Try these progressively more explicit prompts:

Test A: Original prompt

opencode
> Create a todo.md file with 3 sample tasks

Test B: Explicit mode directive

opencode
> /mode build
> Create a todo.md file with 3 sample tasks

Test C: Tool-specific instruction

opencode
> Use the write tool to create a file called todo.md with 3 tasks

Test D: Simple file write

opencode
> Write a file called hello.txt with the text "Hello World"

Test E: Code generation (sometimes works better)

opencode
> Create a hello.py file that prints "Hello World"

Step 3: Check Open Code CLI Agent Configuration

Open Code CLI may require specific configuration for agent/tool usage. Check:

# Look for Open Code CLI config
cat ~/.opencode/config.json

# Check if there's a workspace-specific config
cat .opencode/config.json

Step 4: Compare with Cloud Model (Claude)

To isolate whether this is an Ollama-specific issue:

# Test with Claude (if you have API key configured)
opencode --model claude-sonnet-4
> Create a todo.md file with 3 sample tasks

If Claude works but Ollama doesn't, this is a local model tool usage issue.

✅ Solution: Use Qwen3 Models for File Operations

Primary Solution: Switch to Qwen3 Models

For ANY task requiring file creation or modification, use Qwen3 models:

# Recommended: qwen3:8b-16k (tested and confirmed working)
opencode --model ollama/qwen3:8b-16k
> Create a todo.md file with 3 sample tasks
# ✅ This works!

Alternative Qwen3 models (likely also work):

# Standard context (faster than 16k)
opencode --model ollama/qwen3:8b
> Add type hints to utils/helpers.py

# Small/fast variant
opencode --model ollama/qwen3:4b
> Create a simple hello.py file

Tool Call Format

Qwen3 models use this format to call file tools:

{
  "name": "write",
  "arguments": {
    "content": "# Todo List\n\n- Task 1\n- Task 2",
    "filePath": "/absolute/path/to/file.md"
  }
}

Think Mode Handling

Qwen3 models enter verbose "thinking mode" before execution:

  • Accept it - Think mode doesn't prevent file creation
  • Benefit - Provides detailed reasoning about the task
  • Workaround - Use /mode build to minimize thinking (may not fully suppress)
opencode --model ollama/qwen3:8b-16k
> /mode build
> Create a todo.md file with 3 tasks
# Still shows some thinking, but completes successfully

Why Custom Prompts Won't Help

Important: Custom system prompts or Modelfiles will NOT add tool usage to models lacking this capability:

# ❌ This will NOT work - Mistral Nemo lacks tool training
ollama create opencode-mistral -f custom-modelfile.txt
opencode --model ollama/opencode-mistral
> Create a file
# Still won't create files - model lacks function calling ability

Tool usage requires specific training data and model architecture changes, not just prompt engineering.

Use Cases by Model Type

✅ Qwen3 Models (Full Tool Usage)

Use for:

  • ✅ File creation and modification
  • ✅ Code generation
  • ✅ Refactoring with file changes
  • ✅ Multi-file operations
  • ✅ Code review (read-only)
  • ✅ Analysis and planning

Example workflows:

# File creation
opencode --model ollama/qwen3:8b-16k
> Create a Python class for user authentication

# Refactoring
> Refactor UserService to use dependency injection

# Multi-file changes
> Add type hints to all files in src/utils/

⚠️ Mistral Nemo & Granite (Analysis Only)

Use for:

  • ✅ Code review (read-only)
  • ✅ Analysis and suggestions
  • ✅ Architecture planning
  • ✅ Documentation review
  • ❌ CANNOT create or modify files

Example workflows:

# Code review (works great)
opencode --model ollama/mistral-nemo:12b-instruct-2407-q4_K_M
> /mode review
> Analyze the security of src/auth/ directory

# Planning (works great)
> /mode plan
> Analyze the codebase architecture and suggest improvements

# Implementation (FAILS - no file creation)
> /mode build
> Implement the suggested improvements
# ❌ Will analyze but NOT create files

Hybrid Workflow (Best of Both)

Use different models for different phases:

# Phase 1: Analysis with Mistral Nemo (best quality)
opencode --model ollama/mistral-nemo:12b-instruct-2407-q4_K_M
> /mode review
> Review src/auth/ for security issues
# ✅ Get excellent analysis and recommendations

# Phase 2: Implementation with Qwen3 (tool usage)
opencode --model ollama/qwen3:8b-16k
> /mode build
> Implement the security fixes recommended above
# ✅ Actually creates/modifies files

Common Issues & Solutions

Issue: "Model plans but doesn't create files"

Cause: Using Mistral Nemo or Granite for file operations

Solution: Switch to Qwen3 model

# Instead of this:
opencode --model ollama/mistral-nemo:12b-instruct-2407-q4_K_M
> Create a file

# Use this:
opencode --model ollama/qwen3:8b-16k
> Create a file

Issue: "Verbose thinking mode slows down tasks"

Cause: Qwen3 models have built-in thinking behavior

Solutions:

  1. Accept it - File still gets created successfully
  2. Use /mode build - May reduce (but not eliminate) thinking
  3. Consider the benefit - Think mode provides useful reasoning
  4. Use smaller model - qwen3:8b or qwen3:4b may be faster

Issue: "Want best code quality AND file creation"

Cause: Mistral Nemo has best quality but no tool usage

Solution: Hybrid approach

# Get analysis from Mistral Nemo
opencode --model ollama/mistral-nemo:12b-instruct-2407-q4_K_M
> /mode plan
> Design the authentication system

# Implement with Qwen3
opencode --model ollama/qwen3:8b-16k
> /mode build
> Implement the authentication system designed above

Resources

Quick Reference

Model Selection Flowchart

Need to create/modify files?
├─ YES → Use Qwen3 models
│   ├─ Multi-file/complex → qwen3:8b-16k (16k context)
│   ├─ Standard tasks → qwen3:8b (8k context, faster)
│   └─ Simple/quick → qwen3:4b (fastest)
│
└─ NO (analysis only) → Any model
    ├─ Best quality → mistral-nemo:12b-instruct-2407-q4_K_M
    ├─ Fast analysis → granite3.1-moe
    └─ Extended context → qwen3:8b-16k

Command Templates

File creation (Qwen3 required):

opencode --model ollama/qwen3:8b-16k
> Create/modify/refactor [description]

Code review (any model):

opencode --model ollama/mistral-nemo:12b-instruct-2407-q4_K_M
> /mode review
> Review [file/directory]

Hybrid workflow:

# Step 1: Analyze
opencode --model ollama/mistral-nemo:12b-instruct-2407-q4_K_M
> /mode plan
> [analysis task]

# Step 2: Implement
opencode --model ollama/qwen3:8b-16k
> /mode build
> [implementation task]

Update Log

2025-11-18:

  • ✅ RESOLVED: Confirmed Qwen3 models have tool usage capabilities
  • ✅ TESTED: qwen3:8b-16k successfully creates files
  • ❌ CONFIRMED: granite3.1-moe and mistral-nemo:12b-instruct-2407-q4_K_M lack tool usage
  • 📝 DOCUMENTED: Root cause is model training, not Open Code CLI issue
  • 📝 PUBLISHED: Workarounds and hybrid workflow strategies