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 shard list
flint workspace list

# Sync to reconcile state
flint sync

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.json
# - .flint/
# - Mesh/

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

# If .flint/ corrupted, regenerate
rm -rf .flint/
flint sync

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

Shard Not Working

Symptom: Shard commands fail or agent doesn't recognize shard capabilities.

Solutions:

# Check if installed
flint shard list

# If not listed, install it
flint shard install NUU-Cognition/shard-projects

# Or add to flint.toml and sync
# [shards]
# projects = { source = "NUU-Cognition/shard-projects" }
flint sync

# If listed but not working, check health
flint shard check

# Update all shards
flint shard update

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

@Shards/Projects/init-proj.md

Configuration Out of Sync

Symptom: Changes to flint.toml not reflected.

Solution:

flint sync

This reads flint.toml and updates installed shards, 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>

Connection Issues

Symptom: Connections show as unfulfilled or broken.

Solution:

# Check connection status
flint connection list

# Fulfill from registry
flint connection fulfill --all

# Or fulfill with explicit path
flint connection fulfill "Name" --target /path/to/flint

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 document.

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/index/
flint sync

CLI Not Found

Symptom: flint: command not found

Solutions:

Reinstall via npm:

npm install -g @nuucognition/flint

If still not found, check your PATH:

# Check npm global bin directory
npm bin -g

# Verify it's in your PATH
which flint

Resetting a Flint

If all else fails, you can reset runtime state:

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

# Regenerate everything from flint.toml
flint sync

Warning: This removes:

• Index (will be rebuilt)
• Reference/connection fulfillments (will need re-fulfillment)
• Local state files

Your notes in Mesh/, shards in Shards/, and mods in Mods/ are preserved. Your flint.toml and flint.json 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