Skip to content
mdkg Docs

Troubleshooting

mdkg validate reports stale cache warnings

Section titled “mdkg validate reports stale cache warnings”

Run:

Terminal window
mdkg index
mdkg validate --summary

Generated indexes are rebuildable access caches. Markdown graph files remain authoritative.

mdkg goal next returns no node

Section titled “mdkg goal next returns no node”

Check the selected goal:

Replace GOAL_ID with a concrete goal id from your repo:

Terminal window
mdkg goal current --json
mdkg goal next GOAL_ID --json

Completed, achieved, archived, or paused goals may correctly return no actionable node. Clear stale selection when no work should be active:

Terminal window
mdkg goal clear --json

In a fresh repo, node: null can simply mean no work exists yet. Continue with If no work exists yet and create a small task before expecting goal next to route.

There are many heading warnings

Section titled “There are many heading warnings”

Use bounded output first:

Terminal window
mdkg validate --summary --json --limit 20
mdkg format --headings --dry-run --summary --json --limit 20

Apply formatting only after reviewing the diff.

A repo has project DB runtime files

Section titled “A repo has project DB runtime files”

Runtime DB files are local state. Verify the DB before deciding whether anything needs cleanup:

Terminal window
mdkg db verify --json
mdkg db stats --json

Do not commit .mdkg/db/runtime/ files.

A handoff warns about raw markers

Section titled “A handoff warns about raw markers”

Review the handoff manually. Warnings are aids, not proof that the content is safe or unsafe. Remove raw secrets, tokens, provider payloads, raw prompt dumps, and bulky runtime traces before sharing.