Troubleshooting¶

`qlens` command not found¶

Confirm that the virtual environment is active and reinstall the editable package:

pip install -e ".[docs,dev]"
qlens --version

Fallback:

python -m qlens --version

Registry reported as stale¶

Rebuild it:

qlens registry
qlens registry --check

The second command should report stale: false.

Validation reports a broken reference¶

Show the referencing object and target:

qlens show RSN-000001
qlens show EVD-000001
qlens graph RSN-000001 --depth 2

Correct the OID in the canonical YAML record, then run:

qlens repo validate

Duplicate OID¶

Search filenames and content for the duplicate:

Linux/macOS:

grep -R "OID-TO-FIND" repository/objects

PowerShell:

Get-ChildItem repository\objects -Recurse -File | Select-String "OID-TO-FIND"

Keep one stable identity. Do not silently renumber an established object without a migration record.

Invalid lifecycle transition¶

Inspect the current object:

qlens show QST-000001

Use an allowed next state rather than editing status directly. Lifecycle enforcement protects traceability.

MkDocs missing¶

Install documentation dependencies:

pip install -e ".[docs]"
mkdocs --version

Generated workspace appears outdated¶

qlens build
mkdocs serve

`qlens new` creates an incomplete research record¶

This is expected. The command creates a schema-aware scaffold. Open the generated file and complete the object-specific content and relationships before verification.

A command from an older proposal does not exist¶

Use:

qlens --help

Only commands shown by the installed CLI are normative for the current release. Ideas such as nested qlens object, qlens nur, qlens publish, snapshot restoration, and automatic AI acceptance remain roadmap concepts unless implemented in a later version.