Troubleshooting

Troubleshooting

This guide covers common issues and their solutions when using bkmr.

Installation Issues

Binary Not Found After Install

Problem: bkmr: command not found after installation

Solutions:

1. Cargo Install Path Not in PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

# Verify
which bkmr

2. pip/pipx Install Path:

# Check pip install location
pip show bkmr | grep Location

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

3. Brew Install:

# Verify brew installation
brew list | grep bkmr

# Reinstall if needed
brew reinstall bkmr

Version Check

# Verify installation
bkmr --version

# Should show: bkmr x.x.x

Database Issues

Database Not Found

Problem: Error: Database not found at ~/.config/bkmr/bkmr.db

Solutions:

1. Create Database:

# Create at default location
bkmr create-db ~/.config/bkmr/bkmr.db

# Or create at custom location
bkmr create-db ~/custom/path/bkmr.db
export BKMR_DB_URL=~/custom/path/bkmr.db

2. Check Environment Variable:

# Verify database path
echo $BKMR_DB_URL

# Set if not configured
export BKMR_DB_URL="$HOME/.config/bkmr/bkmr.db"

# Add to shell profile for persistence
echo 'export BKMR_DB_URL="$HOME/.config/bkmr/bkmr.db"' >> ~/.bashrc

3. Check File Permissions:

# Verify file exists and is readable
ls -la ~/.config/bkmr/bkmr.db

# Fix permissions if needed
chmod 644 ~/.config/bkmr/bkmr.db

Database Corruption

Problem: Database file corrupted or damaged

Solution:

If you have backups:

# Check for automatic migration backups
ls -la ~/.config/bkmr/bkmr_backup_*.db

# Restore from backup
cp ~/.config/bkmr/bkmr_backup_20250412.db ~/.config/bkmr/bkmr.db

If no backups exist:

# Create new database
bkmr create-db ~/.config/bkmr/bkmr_new.db

# Use new database
export BKMR_DB_URL=~/.config/bkmr/bkmr_new.db

# Re-import content if possible

Database Lock Errors

Problem: Error: database is locked

Solutions:

1. Close other bkmr instances:

# Check for running bkmr processes
ps aux | grep bkmr

# Kill if stuck
pkill bkmr

2. Check for stale locks:

# Remove SQLite lock files if they exist
rm -f ~/.config/bkmr/bkmr.db-shm
rm -f ~/.config/bkmr/bkmr.db-wal

Search Issues

No Results Found

Problem: Search returns no results when content exists

Troubleshooting:

1. Check spelling:

# Try different spellings
bkmr search "docker"
bkmr search "dokcer"  # typo

# Use wildcard
bkmr search "dock*"

2. Verify content exists:

# List all bookmarks
bkmr search ""

# Check specific tags
bkmr tags
bkmr search -t python

3. Test full-text search:

# Try different search patterns
bkmr search "python"              # Simple term
bkmr search "python async"        # Multiple terms
bkmr search "python OR rust"      # Boolean
bkmr search "\"async await\""     # Exact phrase

4. Try fuzzy finder:

# Fuzzy finder is more forgiving
bkmr search --fzf

Tag Filtering Not Working

Problem: Tag filters don't return expected results

Debugging:

1. Verify tag exists:

# List all tags
bkmr tags

# Check if bookmark has expected tags
bkmr show <id>

2. Check tag filter syntax:

# Correct syntax
bkmr search -t python,async      # AND (both tags required)
bkmr search -T python,rust        # OR (any tag)
bkmr search -n deprecated         # NOT (exclude tag)

# Common mistakes
bkmr search --tags python async   # Wrong: space-separated
bkmr search -t python async       # Wrong: 'async' treated as search term

3. System tags case-sensitive:

# Correct
bkmr search -t _snip_

# Wrong
bkmr search -t _Snip_
bkmr search -t SNIP

FZF Not Working

Problem: bkmr search --fzf fails or doesn't show interface

Solutions:

1. Install fzf:

# macOS
brew install fzf

# Linux (Debian/Ubuntu)
sudo apt install fzf

# Linux (Arch)
sudo pacman -S fzf

# Verify installation
which fzf
fzf --version

2. Test fzf directly:

# Test fzf works
echo -e "line1\nline2\nline3" | fzf

3. Check BKMR_FZF_OPTS:

# Verify environment variable
echo $BKMR_FZF_OPTS

# Test without custom options
unset BKMR_FZF_OPTS
bkmr search --fzf

4. Use skim alternative:

# bkmr uses skim internally, which is fzf-compatible
# If issues persist, check skim functionality

Content Type Issues

System Tags Not Working

Problem: Content not behaving with expected action (copy, open, execute)

Debugging:

1. Verify system tag:

# Check bookmark has correct system tag
bkmr show <id> | grep Tags

# Should include: _snip_, _shell_, _md_, _env_, or _imported_

2. Add missing system tag:

# Add system tag if missing
bkmr update -t _snip_ <id>        # For snippets
bkmr update -t _shell_ <id>       # For shell scripts
bkmr update -t _md_ <id>          # For markdown
bkmr update -t _env_ <id>         # For environment variables

3. Test action manually:

# Test open action
bkmr open <id>

# Enable debug logging
bkmr -d open <id>
bkmr -d -d open <id>  # More verbose

Clipboard Issues

Problem: Content not copying to clipboard

Solutions:

macOS:

# Verify pbcopy works
echo "test" | pbcopy
pbpaste

Linux (X11):

# Install xclip if missing
sudo apt install xclip      # Debian/Ubuntu
sudo pacman -S xclip        # Arch

# Test xclip
echo "test" | xclip -selection clipboard
xclip -o -selection clipboard

Linux (Wayland):

# Verify Wayland clipboard support
echo $XDG_SESSION_TYPE  # Should show "wayland"

# Install wl-clipboard if missing
sudo apt install wl-clipboard      # Debian/Ubuntu
sudo pacman -S wl-clipboard        # Arch

# Test wl-clipboard
echo "test" | wl-copy
wl-paste

Compatibility Check:

# bkmr automatically detects clipboard system
# Run with debug to see which system is used
bkmr -d yank <id>

Shell Script Issues

Scripts Not Executing

Problem: Shell scripts don't execute when opened

Debugging:

1. Verify system tag:

# Check bookmark has _shell_ tag
bkmr show <id> | grep "_shell_"

2. Check interactive mode:

# Test direct execution
bkmr open --no-edit <id>

# Check configuration
echo $BKMR_SHELL_INTERACTIVE

# Disable interactive mode temporarily
BKMR_SHELL_INTERACTIVE=false bkmr open <id>

3. Test script directly:

# Extract script content
bkmr show <id>

# Copy content and test in shell manually

4. Check for errors:

# Enable debug logging
RUST_LOG=debug bkmr open <id>

Interactive Editor Not Appearing

Problem: Expected interactive editing but script executes directly

Solutions:

1. Check configuration:

# Verify interactive mode enabled
echo $BKMR_SHELL_INTERACTIVE  # Should be "true" or unset

# In config.toml
cat ~/.config/bkmr/config.toml | grep -A 1 "shell_opts"
# Should show: interactive = true

2. Manually enable:

# Via environment variable
export BKMR_SHELL_INTERACTIVE=true

# Or in config.toml
[shell_opts]
interactive = true

Shell Function Stubs Not Working

Problem: Generated functions not available or not executing

Debugging:

1. Verify stub generation:

# Test stub generation
bkmr search --shell-stubs

# Should output function definitions

2. Check if sourced:

# Verify functions are loaded
declare -F | grep backup
declare -F | grep deploy

# Re-source if needed
source <(bkmr search --shell-stubs)

3. Check for name conflicts:

# Check if function name conflicts with existing command
type backup-database

# If conflict, use namespacing
bkmr search --shell-stubs | sed 's/^/bkmr_/' > ~/.config/bkmr/functions.sh
source ~/.config/bkmr/functions.sh

4. Verify bookmark has shell tag:

# Only bookmarks with _shell_ tag generate stubs
bkmr search -t _shell_ --json | jq length

Template Interpolation Issues

Templates Not Rendering

Problem: Templates show raw syntax instead of resolved values

Debugging:

1. Check where interpolation occurs:

# Search results: Requires --interpolate flag
bkmr search --interpolate "backup"

# FZF mode: Automatic
bkmr search --fzf "backup"

# Open action: Automatic
bkmr open <id>

2. Verify template syntax:

# Correct syntax
{{ current_date }}
{{ env("HOME") }}
{{ "hostname" | shell }}

# Check for typos
{{ current_date }}      # Correct
{{ currentdate }}       # Wrong
{{ current_date) }}     # Wrong: mismatched braces

3. Test incrementally:

# Start simple
bkmr add "{{ current_date }}" test,_snip_ --title "Test"

# Test rendering
bkmr search --interpolate "Test"
bkmr open <id>  # Should copy resolved date

4. Check logs:

# Enable debug logging
RUST_LOG=debug bkmr open <id> 2>&1 | grep -i template

Environment Variables Not Expanding

Problem: {{ env("VAR") }} not resolving

Solutions:

1. Verify variable exists:

# Check environment variable
echo $VARIABLE_NAME

# Set if missing
export VARIABLE_NAME="value"

2. Use fallback values:

# Always provide defaults
{{ env("API_KEY", "default-key") }}
{{ env("ENVIRONMENT", "development") }}

3. Check variable name:

# Correct
{{ env("HOME") }}

# Wrong
{{ env($HOME) }}      # Don't use $
{{ env("home") }}     # Case-sensitive

Shell Commands Not Executing

Problem: {{ "command" | shell }} returns empty or errors

Solutions:

1. Test command directly:

# Verify command works
git branch --show-current
hostname

2. Check command in PATH:

# Verify command exists
which git
which hostname

3. Use full paths if needed:

# Relative path might fail
{{ "git" | shell }}

# Use full path
{{ "/usr/bin/git branch --show-current" | shell }}

4. Add error handling:

# Use fallbacks
{{ "git branch --show-current || echo 'no-git'" | shell }}

Template Syntax Conflicts

Problem: Scripts with Go templates (GitHub CLI, Docker, Helm) fail

Solution - Use Dynamic Construction:

# Problem: This fails
gh run list --template '{{range .}}{{.name}}{{end}}'

# Solution: Construct template dynamically
OPEN_BRACE='{'
CLOSE_BRACE='}'
TEMPLATE="${OPEN_BRACE}${OPEN_BRACE}range .${CLOSE_BRACE}${CLOSE_BRACE}..."
gh run list --template "$TEMPLATE"

Tools with Known Conflicts:

• GitHub CLI (gh)
• Docker Compose
• Helm charts
• Kubernetes manifests
• Terraform

See Template Interpolation for detailed solutions.

File Import Issues

Import Fails

Problem: bkmr import-files fails with errors

Debugging:

1. Check file exists:

# Verify file path
ls -la ~/scripts/backup.sh

# Check permissions
ls -la ~/scripts/

2. Verify frontmatter syntax:

# YAML frontmatter
---
name: "Script Name"
tags: ["tag1", "tag2"]
---

# Hash-style frontmatter
# name: Script Name
# tags: tag1, tag2

3. Test with dry-run:

# Preview what would be imported
bkmr import-files ~/scripts/ --dry-run

# Check for errors in output

4. Enable debug logging:

# See detailed import process
RUST_LOG=debug bkmr import-files ~/scripts/

Base Path Not Found

Problem: Error: Base path 'SCRIPTS_HOME' not found in configuration

Solution:

1. Add to config.toml:

# Edit config
vim ~/.config/bkmr/config.toml

# Add base path section
[base_paths]
SCRIPTS_HOME = "$HOME/scripts"
DOCS_HOME = "$HOME/documents"

2. Verify configuration:

# Generate default config to see format
bkmr --generate-config | grep -A 5 "base_paths"

# Check current config
cat ~/.config/bkmr/config.toml | grep -A 5 "base_paths"

Smart Editing Opens Wrong File

Problem: bkmr edit <id> opens wrong file or fails to open source file

Debugging:

1. Check if file-imported:

# Verify bookmark has file_path
bkmr show <id> | grep -i "file"

2. Verify source file exists:

# Check file path
bkmr show <id>

# Test if file exists (resolve base paths manually)
ls -la ~/scripts/backup.sh

3. Force database editing:

# Edit database content instead of source file
bkmr edit <id> --force-db

4. Check $EDITOR:

# Verify editor is configured
echo $EDITOR

# Set if missing
export EDITOR=vim  # or nano, code, etc.

LSP Integration Issues

No Completions Appearing

Problem: LSP snippets not showing in editor

Debugging:

1. Verify snippets exist:

# Check for snippets
bkmr search -t _snip_

# Check language-specific
bkmr search -t _snip_,rust

2. Test LSP server:

# Test basic connectivity
echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}' | bkmr lsp

# Should return JSON with capabilities

3. Check bkmr version:

# LSP requires 4.31.0+
bkmr --version

4. Verify editor configuration:

# Neovim
:LspInfo  # Check if bkmr_lsp attached

# VS Code
# Check Output → Language Server logs

Snippets Not Filtered by Language

Problem: All snippets appear regardless of file type

Solutions:

1. Tag snippets with language:

# Ensure language tags exist
bkmr update -t rust <id>
bkmr update -t python <id>

2. Verify file type detection:

# In Neovim
:set filetype?

# Should match language ID (python, rust, javascript)

3. Test language filtering:

# Use test scripts
python3 scripts/lsp/list_snippets.py --language rust --debug

LSP Server Crashes

Problem: LSP server stops responding

Debugging:

1. Enable debug logging:

# Start LSP with debug output
RUST_LOG=debug bkmr lsp 2>/tmp/bkmr-lsp.log

# Watch logs
tail -f /tmp/bkmr-lsp.log

2. Check for database issues:

# Verify database accessible
ls -la $BKMR_DB_URL

# Test database operations
bkmr search ""

3. Restart LSP server:

# Stop current instance
pkill -f "bkmr lsp"

# Restart from editor
# Neovim: :LspRestart

Configuration Issues

Config File Not Loaded

Problem: Configuration file settings not applied

Debugging:

1. Check file location:

# Default location
ls -la ~/.config/bkmr/config.toml

# Verify syntax
bkmr --generate-config > /tmp/test.toml
diff ~/.config/bkmr/config.toml /tmp/test.toml

2. Check TOML syntax:

# Common syntax errors
[fzf_opts]
height = "70%"     # Correct: quoted string
height = 70%       # Wrong: not quoted

[shell_opts]
interactive = true # Correct: boolean
interactive = "true" # Wrong: string (should be boolean)

3. Test with --config flag:

# Use explicit config file
bkmr --config ~/.config/bkmr/config.toml search "test"

Environment Variables Not Working

Problem: Environment variables not recognized

Solutions:

1. Verify variables are exported:

# Check if set
echo $BKMR_DB_URL
echo $BKMR_FZF_OPTS

# Check if exported
export | grep BKMR

2. Add to shell profile:

# ~/.bashrc or ~/.zshrc
export BKMR_DB_URL="$HOME/.config/bkmr/bkmr.db"
export BKMR_SHELL_INTERACTIVE="true"

# Reload shell
source ~/.bashrc

3. Test precedence:

# Environment variables override config.toml
BKMR_DB_URL=/tmp/test.db bkmr search ""

Database Reset and Recovery

Sometimes you need to reset your database and recreate it with current data.

Complete Database Reset

Process:

1. Export existing data (if applicable):

# Export to JSON
bkmr search --json "" > backup.json

# Note: CSV export requires custom scripts

2. Create fresh database:

# Create new database
bkmr create-db ~/.config/bkmr/bkmr_new.db

# Switch to new database
mv ~/.config/bkmr/bkmr.db ~/.config/bkmr/bkmr_old.db
mv ~/.config/bkmr/bkmr_new.db ~/.config/bkmr/bkmr.db

3. Re-import content:

# Import files
bkmr import-files ~/scripts/ --base-path SCRIPTS_HOME

# Manually add critical bookmarks
# Or write script to parse backup.json and re-add

4. Recreate embeddings (if using semantic search):

# Mark bookmarks as embeddable
bkmr set-embeddable <id> --enable

# Backfill embeddings
bkmr --openai backfill

Backup Best Practices

Automated Backups:

# Add to crontab for daily backups
backup-bkmr() {
    local backup_dir="$HOME/backups/bkmr"
    local date=$(date +%Y%m%d)
    mkdir -p "$backup_dir"
    cp ~/.config/bkmr/bkmr.db "$backup_dir/bkmr-$date.db"

    # Keep only last 30 days
    find "$backup_dir" -name "bkmr-*.db" -mtime +30 -delete
}

# Run daily at 2 AM
# Crontab: 0 2 * * * /path/to/backup-bkmr

Debug Mode

Enabling Debug Output

Basic debugging:

# Single debug flag
bkmr -d search "test"

# Double debug flag (more verbose)
bkmr -d -d search "test"

# Maximum verbosity with RUST_LOG
RUST_LOG=debug bkmr search "test"
RUST_LOG=trace bkmr search "test"  # Very verbose

Redirect debug output:

# Save to file for analysis
RUST_LOG=debug bkmr search "test" 2>/tmp/bkmr-debug.log

# View log
cat /tmp/bkmr-debug.log

Common Debug Patterns

Test specific components:

# Search debugging
RUST_LOG=debug bkmr search "test" 2>&1 | grep -i "search"

# Action debugging
RUST_LOG=debug bkmr open <id> 2>&1 | grep -i "action"

# Template debugging
RUST_LOG=debug bkmr open <id> 2>&1 | grep -i "template"

Getting Help

If you're still experiencing issues:

1. Check version:

bkmr --version
# Ensure you're using latest version

2. Search existing issues:

• GitHub Issues: https://github.com/sysid/bkmr/issues
• Wiki: https://github.com/sysid/bkmr/wiki

3. Create bug report with:

• bkmr version
• Operating system
• Steps to reproduce
• Debug logs (RUST_LOG=debug)
• Configuration files (sanitized)

4. Community support:

• GitHub Discussions
• Issue tracker with question label

Related Pages

• Installation - Installation troubleshooting
• Configuration - Configuration details
• Basic Usage - Common usage patterns
• Search and Discovery - Search troubleshooting
• Shell Scripts - Shell execution issues
• Template Interpolation - Template issues
• Editor Integration - LSP troubleshooting