Troubleshooting

Common current issues and the fastest reliable ways to recover from them.

“Not inside a Flint”

Many commands auto-detect the active workspace from the current directory.

Fix:

• cd into the Flint root
• or pass --path <dir> where the command supports it

A Flint Does Not Appear in flint list

Register it:

flint register /path/to/flint

If the registry entry is stale, re-register it and then inspect status:

flint register /path/to/flint --force
flint list --status

A Declared Codebase Reference Is Still Unfulfilled

Declare and fulfill it explicitly:

flint reference codebase "Flint"
flint fulfill codebase "Flint" /path/to/flint
flint reference list

Remember that fulfill currently supports codebase resources only. Flint references are fulfilled through the registry and sync flow.

A Flint Reference Will Not Resolve

Make sure the target Flint is registered locally:

flint list
flint register /path/to/target-flint

Then run:

flint sync

flint source meshexport add Cannot Find the Source Flint

Source mesh exports resolve through the local registry. Register the source Flint first, then try again.

Shards Are Installed but the Workspace Still Feels Broken

This usually means the workspace declaration and the local shard state have drifted apart.

Run:

flint shard check
flint shard heal
flint sync

This is especially relevant because shards are the cognitive programs the environment depends on. If shards are broken, the agent-facing behavior of the workspace is broken too.

A Workspace Repository Is Declared but Missing on Disk

Check status and then restore it:

flint workspace list
flint workspace update "<name>"

A Source Repository Is Declared but Missing on Disk

Check status and refresh it:

flint source repo list
flint source repo update "<name>"

Export Build Says Nothing Is Declared

Make sure the root note has the #export tag, then declare and build:

flint export scan
flint export list
flint export build

The Server or Runtime Is Not Available

Start the server first:

flint server start
flint server status

If flint runtime is unavailable, remember that the runtime command group is dev-gated in the current CLI.

Headless or Interactive Agent Commands Fail

For flint agent claude, make sure Claude Code is installed.

For flint code codex, make sure Codex is installed.

For any agent workflow, also check that the workspace has the shards and references the agent expects. Flint can only execute the cognitive programs that are actually installed and synced locally.

.obsidian Is Broken

Use the built-in recovery commands:

flint obsidian update
flint obsidian reset --force

flint git sync Stops on a Rebase Conflict

Resolve the conflict markers in the affected files, then rerun:

flint git sync

The current implementation detects an in-progress rebase and continues the sync flow when rerun.