Troubleshooting

Common issues and solutions for ZotMD.

Configuration Issues

Config not found

$ zotmd sync
Error: Not configured. Run 'zotmd config' first.

Solution: Run zotmd config to create the config file.

Invalid API key

$ zotmd config
Testing connection to Zotero...
Error: Failed to connect to Zotero API.

Solutions:

Regenerate API key at zotero.org/settings/keys/new
Ensure "Allow library access" is checked
Check for typos (keys are case-sensitive)

Invalid library ID

✗ Error: Library not found (403 Forbidden)

Solutions:

Verify library ID at zotero.org/settings/keys
Ensure library_type matches (user vs group)
For groups, ensure you're a member

Permission denied (output directory)

Error: Permission denied: /restricted/path

Solutions:

Choose a directory you have write access to
Create directory first: mkdir -p ~/notes/references
Check permissions: ls -ld ~/notes/references

Installation Issues

Command not found: zotmd

Problem:

$ zotmd --help
zotmd: command not found

Solutions:

If installed with uv:

# Ensure uv's bin directory is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
uv tool list

If installed with pipx:

# Ensure pipx path
pipx ensurepath
source ~/.zshrc

Reinstall:
```
uv tool install --force zotmd
```

Python version too old

Problem:

ERROR: Package requires Python >=3.13

Solution:

# Install Python 3.13+ with uv
uv python install 3.13

# Or use system package manager
# macOS:
brew install python@3.13

# Linux:
sudo apt install python3.13

Connection Issues

Cannot connect to Zotero

Problem:

$ zotmd status
✗ Error: Connection refused

Solutions:

Enable API access:
Zotero -> Settings -> Advanced -> Miscellaneous
Check "Allow other applications to access Zotero"
Verify credentials:
```
zotmd config  # Re-enter credentials
```

Test API manually:

curl "https://api.zotero.org/users/YOUR_ID/items?limit=1&key=YOUR_KEY"

403 Forbidden Error

Problem:

✗ Error: 403 Forbidden

Causes & Solutions:

Wrong library_type:
Personal library: Use library_type = "user"
Group library: Use library_type = "group"
Invalid API key:
Regenerate at zotero.org/settings/keys/new
Ensure "Allow library access" is checked
Wrong library ID:
Verify at zotero.org/settings/keys
For groups: Use group ID, not user ID

Rate Limiting

Problem:

✗ Error: 429 Too Many Requests

Solution: Wait a few minutes before retrying. Zotero API has rate limits: - Personal tier: 120 requests/minute - Group tier: Shared across all members

Sync Issues

Items missing citation keys

Problem:

Skipped 45 items without citation keys

Solution:

Install Better BibTeX:
Download: retorque.re/zotero-better-bibtex
Zotero -> Tools -> Add-ons -> Install from File
Generate citation keys:
Select all items in Zotero
Right-click -> Better BibTeX -> Refresh BibTeX key
Re-sync:
```
zotmd sync
```

Annotations not appearing

Problem: PDF highlights not showing in Markdown files.

Solutions:

Ensure PDF is in Zotero:
Attachment must be stored in Zotero (not linked file)
Check: Item has PDF icon, not link icon
Annotations must be created in Zotero:
Use Zotero's built-in PDF reader
External annotations (Adobe, Preview) won't sync
Force re-sync:
```
zotmd sync --full
```

Deleted items reappearing

Problem: Deleted Markdown files come back after sync.

Cause: Items still exist in Zotero library.

Solution:

Delete from Zotero first:
Delete item in Zotero
Empty Zotero trash
Run zotmd sync
Or remove from filesystem only:
Set deletion_behavior = "delete" in config
Files won't be recreated if deleted locally

User notes being overwritten

Problem: Custom notes in Markdown files are lost after sync.

Solution:

Place notes in the designated section:

## Notes
<!-- Add your notes below this line -->
<!-- They will be preserved across syncs -->

Your custom notes here...

Content above this section will be regenerated on each sync.

Database Issues

Corrupted database

Problem:

Error: database disk image is malformed

Solution:

Backup current database:

# macOS
cp ~/.local/share/zotmd/sync.sqlite ~/sync.sqlite.backup

# Linux
cp ~/.local/share/zotmd/sync.sqlite ~/sync.sqlite.backup

Delete and re-sync:

rm ~/.local/share/zotmd/sync.sqlite
zotmd sync --full

Database locked

Problem:

Error: database is locked

Solution:

Check for other zotmd processes:

ps aux | grep zotmd
kill <PID>  # If found

Remove lock file:

rm ~/.local/share/zotmd/sync.sqlite-journal

File System Issues

Permission denied

Problem:

Error: Permission denied: /path/to/output

Solutions:

Create directory:
```
mkdir -p ~/notes/references
```
Fix permissions:
```
chmod 755 ~/notes/references
```

Choose different path:

zotmd config  # Enter accessible directory

Filename too long

Problem:

OSError: File name too long

Cause: Citation keys longer than filesystem limit (255 chars).

Solution:

Shorten citation key in Better BibTeX:
Right-click item -> Better BibTeX -> Pin/Set citation key
Enter shorter key
Change citation key pattern:
Zotero Settings -> Better BibTeX -> Citation Keys
Use shorter pattern (e.g., [auth:lower][year])

Special characters in filenames

Problem: Files with invalid characters (/, :, *, etc.)

Solution:

ZotMD automatically sanitizes filenames, but if issues persist:

Check citation key:
Avoid: < > : " / \ | ? *
Better BibTeX usually handles this
Manually fix:
Edit citation key in Zotero
Remove problematic characters

Template Issues

Template not found

Problem:

Error: Template file not found: /path/to/template.md.j2

Solutions:

Verify path:
```
ls -l /path/to/template.md.j2
```

Use absolute path in config:

template_path = "/Users/me/templates/custom.md.j2"

Reset to default:

template_path = ""  # Empty uses built-in

Template syntax error

Problem:

jinja2.exceptions.TemplateSyntaxError: unexpected '}'

Solution:

Validate Jinja2 syntax:
Check matching {% ... %}, {{ ... }}
Ensure proper indentation
Test with default template:
```
template_path = ""
```
```
zotmd sync --full
```
Debug template:
```
zotmd sync --verbose
```

Performance Issues

Sync is very slow

Problem: Full sync takes hours for large library.

Solutions:

Use incremental sync:
```
zotmd sync  # Default, not --full
```
Check network:
Zotero API may be slow
Try at different time
Reduce annotation processing:
Large PDFs with many annotations take time
This is expected behavior

High memory usage

Problem: Process using excessive RAM.

Cause: Large library with many annotations.

Mitigation:

Process in batches (not yet supported - feature request)
Close other applications
Increase system swap space

Getting Help

If you encounter an issue not listed here:

Check existing issues: github.com/adbX/zotmd/issues

Run with verbose logging:

zotmd sync --verbose 2>&1 | tee debug.log

Create new issue with:
Error message
Steps to reproduce
debug.log output
OS and Python version
zotmd status output

Useful Diagnostic Commands

# Check config
zotmd status

# Test connection only
zotmd config  # Will test during setup

# View config file
cat ~/.config/zotmd/config.toml  # macOS/Linux

# Check database
sqlite3 ~/.local/share/zotmd/sync.sqlite "SELECT COUNT(*) FROM sync_items;"

# List installed version
uv tool list | grep zotmd