Skip to content

Troubleshooting

Jump to bottom
Zhafron Kautsar edited this page Jan 12, 2026 · 3 revisions

Troubleshooting

Common issues and solutions for OpenCode Memory.

Installation Issues

Port Already in Use

Problem: Web server fails to start because port 4747 is in use.

Solution: Change port in configuration:

{
  "webServerPort": 4748
}

Verify: Check if port is available:

lsof -i :4747

Permission Errors

Problem: Cannot create database or configuration files.

Solution: Fix permissions:

sudo chown -R $USER:$USER ~/.opencode-mem
sudo chown -R $USER:$USER ~/.config/opencode

Build Errors

Problem: TypeScript compilation fails.

Solution:

With Bun:

rm -rf node_modules
bun pm cache rm
bun install
bun run build

Or with npm:

rm -rf node_modules
npm cache clean --force
npm install
npm run build

macOS: Extension Loading Error

Problem: Plugin fails to load with error:

Error: This build of sqlite3 does not support dynamic extension loading
    at loadExtension (unknown)
    at load (/Users/xxx/.cache/opencode/node_modules/sqlite-vec/index.mjs:55:6)

Root Cause:

Apple's SQLite build on macOS disables extension loading for security reasons. Bun uses Apple's SQLite by default for ~50% better performance, but this prevents sqlite-vec from loading.

Solution:

1. Install Homebrew SQLite

brew install sqlite

2. Find the library path

brew --prefix sqlite

This will output something like:

  • Apple Silicon: /opt/homebrew/opt/sqlite
  • Intel Mac: /usr/local/opt/sqlite

3. Configure custom SQLite path

Edit ~/.config/opencode/opencode-mem.jsonc:

{
  "customSqlitePath": "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib"
}

Common paths:

  • Apple Silicon (M1/M2/M3): /opt/homebrew/opt/sqlite/lib/libsqlite3.dylib
  • Intel Mac: /usr/local/opt/sqlite/lib/libsqlite3.dylib

4. Restart OpenCode

The plugin will now use Homebrew's SQLite which supports extension loading.

Auto-Detection: If you don't configure customSqlitePath, the plugin will attempt to auto-detect Homebrew SQLite at common paths. However, manual configuration is recommended for reliability.

Verification: After configuration, check the logs for:

Using custom SQLite library { path: "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib" }

Or if auto-detected:

Auto-detected and using Homebrew SQLite { path: "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib" }

Still Not Working?

Verify Homebrew SQLite installation:

ls -la $(brew --prefix sqlite)/lib/libsqlite3.dylib

Check if the file exists:

file /opt/homebrew/opt/sqlite/lib/libsqlite3.dylib

Verify it's a valid library:

otool -L /opt/homebrew/opt/sqlite/lib/libsqlite3.dylib

Alternative Path: If your Homebrew installation is in a non-standard location:

find /usr/local /opt -name "libsqlite3.dylib" 2>/dev/null | grep homebrew

Then use the full path in your config.

Performance Note: Using Homebrew SQLite on macOS may result in ~50% slower SQLite performance compared to Apple's optimized build. However, this is necessary for extension loading support.

Related Issues:

SQLite Initialization Failed

Problem: Database cannot be created or opened.

Solution:

  1. Check disk space: df -h
  2. Check permissions: ls -la ~/.opencode-mem
  3. Remove corrupted database: rm ~/.opencode-mem/data/*.db
  4. Restart OpenCode

Web Interface Issues

Interface Not Accessible

Problem: Cannot access web interface at configured URL.

Solution:

  1. Verify server is running:
curl http://127.0.0.1:4747/api/stats
  1. Check configuration:
{
  "webServerEnabled": true,
  "webServerPort": 4747,
  "webServerHost": "127.0.0.1"
}
  1. Check firewall settings
  2. Restart OpenCode

Slow Loading

Problem: Web interface loads slowly or times out.

Solution:

  1. Reduce result limit in settings
  2. Run cleanup to reduce database size
  3. Run deduplication
  4. Increase similarity threshold
  5. Use smaller embedding model

Search Not Working

Problem: Search returns no results or errors.

Solution:

  1. Verify embedding model is loaded
  2. Check database exists: ls ~/.opencode-mem/data/
  3. Lower similarity threshold
  4. Restart OpenCode

Memory Operations Issues

Cannot Add Memory

Problem: Memory tool returns error when adding memory.

Solution:

  1. Verify required parameters:
memory({
  mode: "add",
  content: "Your content here",
  scope: "user"
})
  1. Check content is not empty
  2. Verify scope is "user" or "project"
  3. Check database is writable

Search Returns No Results

Problem: Search query returns empty results.

Solution:

  1. Lower similarity threshold:
{
  "similarityThreshold": 0.5
}
  1. Verify memories exist:
memory({ mode: "list", scope: "user" })
  1. Check embedding model is working
  2. Try different search query

Memory Not Found

Problem: Cannot find memory by ID.

Solution:

  1. Verify memory ID is correct
  2. List memories to get valid IDs:
memory({ mode: "list", scope: "user" })
  1. Check memory wasn't deleted
  2. Verify database integrity

Auto-Capture Issues

Auto-Capture Not Working

Problem: Automatic memory capture is not triggering.

Solution:

  1. Verify configuration:
{
  "autoCaptureEnabled": true,
  "memoryModel": "gpt-4",
  "memoryApiUrl": "https://api.openai.com/v1",
  "memoryApiKey": "sk-..."
}
  1. Check API key is valid:
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"
  1. Verify token threshold is reached:
memory({ mode: "auto-capture-stats" })
  1. Check OpenCode logs for errors

No Memories Extracted

Problem: Auto-capture runs but extracts no memories.

Solution:

  1. Increase context window:
{
  "autoCaptureContextWindow": 5
}
  1. Lower token threshold:
{
  "autoCaptureTokenThreshold": 5000
}
  1. Ensure conversation has extractable content
  2. Try different AI model

High API Costs

Problem: Auto-capture is expensive.

Solution:

  1. Switch to cheaper model:
{
  "memoryModel": "gpt-3.5-turbo"
}
  1. Increase threshold:
{
  "autoCaptureTokenThreshold": 20000
}
  1. Reduce context window:
{
  "autoCaptureContextWindow": 2
}
  1. Limit max memories:
{
  "autoCaptureMaxMemories": 5
}

Performance Issues

Slow Search

Problem: Search takes too long to complete.

Solution:

  1. Reduce max memories:
{
  "maxMemories": 3,
  "maxProjectMemories": 5
}
  1. Increase similarity threshold:
{
  "similarityThreshold": 0.7
}
  1. Run deduplication
  2. Use smaller embedding model:
{
  "embeddingModel": "Xenova/all-MiniLM-L6-v2"
}

High Memory Usage

Problem: OpenCode Memory uses too much RAM.

Solution:

  1. Enable auto-cleanup:
{
  "autoCleanupEnabled": true,
  "autoCleanupRetentionDays": 14
}
  1. Reduce shard size:
{
  "maxVectorsPerShard": 25000
}
  1. Use smaller embedding model
  2. Run manual cleanup

Large Database Size

Problem: Database files are very large.

Solution:

  1. Run cleanup:
POST /api/cleanup
{ "retentionDays": 30, "dryRun": false }
  1. Run deduplication:
POST /api/deduplicate
{ "similarityThreshold": 0.9, "dryRun": false }
  1. Vacuum database:
sqlite3 ~/.opencode-mem/data/memories_shard_0.db "VACUUM;"

Embedding Issues

Model Loading Failed

Problem: Embedding model fails to load.

Solution:

  1. Verify model name is correct:
{
  "embeddingModel": "Xenova/nomic-embed-text-v1"
}
  1. Check internet connection (first download)
  2. Clear model cache: rm -rf ~/.cache/huggingface
  3. Try different model

API Embedding Errors

Problem: External embedding API returns errors.

Solution:

  1. Verify API credentials:
{
  "embeddingApiUrl": "https://api.openai.com/v1",
  "embeddingApiKey": "sk-..."
}
  1. Check API endpoint is correct
  2. Verify API key has permissions
  3. Check rate limits
  4. Test API manually:
curl https://api.openai.com/v1/embeddings \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"input": "test", "model": "text-embedding-3-small"}'

Dimension Mismatch

Problem: Vector dimension mismatch errors.

Solution:

Run migration to new dimensions:

POST /api/migrate
{
  "newModel": "Xenova/all-MiniLM-L6-v2",
  "newDimensions": 384
}

Database Issues

Database Locked

Problem: SQLite database is locked.

Solution:

  1. Close all connections
  2. Restart OpenCode
  3. Check for zombie processes:
ps aux | grep opencode
  1. Remove lock file:
rm ~/.opencode-mem/data/*.db-shm
rm ~/.opencode-mem/data/*.db-wal

Corrupted Database

Problem: Database file is corrupted.

Solution:

  1. Backup database:
cp -r ~/.opencode-mem/data ~/.opencode-mem/data.backup
  1. Try recovery:
sqlite3 ~/.opencode-mem/data/memories_shard_0.db ".recover" | \
  sqlite3 ~/.opencode-mem/data/memories_shard_0_recovered.db
  1. If recovery fails, delete and start fresh:
rm ~/.opencode-mem/data/*.db

Shard Creation Failed

Problem: Cannot create new shard.

Solution:

  1. Check disk space: df -h
  2. Check permissions: ls -la ~/.opencode-mem/data
  3. Verify shard size setting:
{
  "maxVectorsPerShard": 50000
}

Configuration Issues

Config Not Loading

Problem: Configuration changes not taking effect.

Solution:

  1. Verify config file location:
cat ~/.config/opencode/opencode-mem.jsonc
  1. Check JSON syntax (JSONC allows comments)
  2. Restart OpenCode
  3. Check logs for validation errors

Invalid Configuration

Problem: Configuration validation errors.

Solution:

  1. Check required fields are present
  2. Verify value types (string, number, boolean)
  3. Ensure thresholds are 0.0-1.0
  4. Validate port numbers (1024-65535)
  5. Check file paths exist

Environment Variables Not Working

Problem: Environment variables not recognized.

Solution:

  1. Export variables before starting OpenCode:
export OPENAI_API_KEY=sk-...
opencode
  1. Add to shell profile:
echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc
source ~/.bashrc
  1. Verify variable is set:
echo $OPENAI_API_KEY

Maintenance Issues

Cleanup Not Working

Problem: Cleanup operation fails or does nothing.

Solution:

  1. Run in dry run mode first:
POST /api/cleanup
{ "retentionDays": 30, "dryRun": true }
  1. Check retention days setting
  2. Verify memories are old enough
  3. Check pinned memories (excluded from cleanup)

Deduplication Errors

Problem: Deduplication fails or removes wrong memories.

Solution:

  1. Use dry run mode:
POST /api/deduplicate
{ "similarityThreshold": 0.9, "dryRun": true }
  1. Adjust similarity threshold
  2. Review duplicate groups before deleting
  3. Backup database first

Migration Stuck

Problem: Migration process hangs or fails.

Solution:

  1. Check logs for errors
  2. Verify new model is valid
  3. Ensure sufficient disk space
  4. Restart migration with smaller batch size
  5. If stuck, restart OpenCode

Logging and Debugging

Enable Debug Logging

Add to configuration:

{
  "logLevel": "debug"
}

Check Logs

OpenCode logs location varies by platform:

Linux:

tail -f ~/.opencode/logs/opencode.log

macOS:

tail -f ~/Library/Logs/OpenCode/opencode.log

Windows:

%APPDATA%\OpenCode\logs\opencode.log

Test API Endpoints

Test REST API manually:

curl http://127.0.0.1:4747/api/stats
curl http://127.0.0.1:4747/api/memories?scope=user

Getting Help

If issues persist:

  1. Check GitHub Issues
  2. Search for similar problems
  3. Open new issue with:
    • OpenCode version
    • OpenCode Memory version
    • Operating system
    • Configuration (redact API keys)
    • Error messages
    • Steps to reproduce

Next Steps

Clone this wiki locally