Troubleshooting Guide

Common issues and how to resolve them.

Quick Diagnostics

When something isn't working:

# Check you're in a Flint
flint --version

# See current state
flint plugin list
flint workspace list

# Repair common issues
flint repair --dry-run

Common Issues

"Not a Flint workspace"

Symptom: Commands fail with "Not a Flint workspace" or similar.

Causes:

• Not in a (Flint) folder
• Missing flint.toml
• Corrupted .flint/ directory

Solutions:

# Check current directory
pwd
ls -la

# Should see:
# - flint.toml
# - .flint/
# - Mesh/

# If flint.toml missing, you're in the wrong folder
cd "(Flint) Your Project"

# If .flint/ corrupted
flint repair

Missing File IDs

Symptom: Files don't appear in index or have id: undefined.

Solution:

# Re-index to add IDs
flint sync

# Or specifically rebuild the index
flint index

Plugin Not Working

Symptom: Plugin commands fail or agent doesn't recognize plugin.

Solutions:

# Check if installed
flint plugin list

# If not listed, add to flint.toml and sync
# [plugins]
# required = ["plugin-name"]
flint sync

# If listed but not working, update all plugins
flint plugin update

For agents: Make sure to read the plugin's init file first:

@Plugins/PluginName/init-shorthand.md

Configuration Out of Sync

Symptom: Changes to flint.toml not reflected.

Solution:

flint sync

This reads flint.toml and updates installed plugins, mods, and state.

Broken Links

Symptom: [Note](/note) links don't resolve or show as broken.

Solutions:

Common causes:

1. Typo in link - fix the spelling
2. Note renamed - update links manually
3. Note deleted - remove or update references

Check what notes exist by browsing Mesh/ or using Obsidian's graph view.

Git Conflicts in .flint/

Symptom: Git shows conflicts in .flint/ files.

Solution:

.flint/ should be gitignored. If you're seeing conflicts:

# Remove from git tracking
git rm -r --cached .flint/

# Ensure .gitignore has the entry
echo ".flint/" >> .gitignore

# Regenerate
flint sync

Workspace References Missing

Symptom: Workspace references show as "missing".

Causes:

• Path doesn't exist on this machine
• Path changed
• Different machine than where reference was created

Solution:

# Check references
flint workspace list

# Re-fulfill with correct path
flint workspace fulfill <name> /correct/path

# Or remove if no longer needed
flint workspace remove <name>

Export Compilation Fails

Symptom: Export build produces errors.

Common causes:

1. Missing notes:

   Error: Note not found: [Missing Note](/missing-note)

   Fix: Create the note or remove the reference from the export manifest.

2. Circular transclusions:

   Error: Circular reference detected

   Fix: Remove the circular embed chain.

3. Invalid output path:

   Error: Cannot write to output

   Fix: Check the Exports/ folder exists.

Building exports:

# List available exports
flint export list

# Build a specific export
flint export build guide

Index Corruption

Symptom: Queries return wrong results or missing files.

Solution:

# Delete and rebuild index
rm -rf .flint/index/
flint sync

Frontmatter Parsing Errors

Symptom: Files not indexed or showing parse errors.

Common causes:

1. Invalid YAML:

   ---
   tags: #tag    # Wrong - needs quotes or array
   ---

   Fix:

   ---
   tags:
     - "#tag"
   ---

2. Missing closing ---:

   ---
   id: abc
   
   # Content  # Missing closing ---

3. Tabs instead of spaces: YAML requires spaces. Check for tab characters.

Performance Issues

Symptom: Commands are slow.

Solutions:

# Check Mesh size
find Mesh -name "*.md" | wc -l

# If very large (1000+), consider:
# 1. Archiving old content
# 2. Using more specific organization

# Clear and rebuild index
rm -rf .flint/
flint sync

CLI Not Found

Symptom: flint: command not found

Solutions:

Reinstall via the install script:

curl -fsSL https://raw.githubusercontent.com/NUU-Cognition/flint/main/install.sh | bash

If still not found, check your PATH:

# Check if the binary exists
ls -la ~/.nuucognition/flint/

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

Repair Command

flint repair fixes many common issues automatically:

# Preview what would be fixed
flint repair --dry-run

# Apply fixes
flint repair

What it fixes:

• Missing standard folders (Mesh/, Exports/, etc.)
• Invalid lock file
• Missing flint.toml
• Missing .gitignore
• Missing registry entries

Resetting a Flint

If all else fails, you can reset runtime state:

# Remove all generated state (keeps your notes)
rm -rf .flint/

# Remove plugins (keeps notes)
rm -rf Plugins/

# Regenerate everything
flint sync

Warning: This removes:

• Index (will be rebuilt)
• Plugin status (plugins will need re-initialization)
• Lock file (will be regenerated)

Your notes in Mesh/ are preserved.

Getting Help

If these solutions don't work:

1. Check documentation:

   • Reference - CLI Commands
   • Reference - Configuration

2. Report issues: https://github.com/nuu-cognition/flint/issues

Include:

• Flint version (flint --version)
• OS and Node version
• Exact error message
• Steps to reproduce

Related

• Reference - CLI Commands - All commands
• Reference - Configuration - Configuration options
• Guide - Quick Start - Getting started