Troubleshooting

MkDocs build fails to import package

Symptom:

• ModuleNotFoundError: No module named 'lingo' from mkdocstrings.

Fix:

• Ensure mkdocstrings Python handler path in mkdocs.yml includes repository root (.), not lingo/.

Worker starts but tasks are not consumed

Check:

• queue routing mode (shared vs task)
• inferred worker queues (lingo launch auto-infers unless overridden)
• worker hostname/private queue behavior for local-placement routes

Distributed dispatch fails when broker unavailable

Behavior:

• language may fall back to local execution depending on path and registered verbs.

Action:

• verify broker URL (redis://...) and backend
• verify Redis is reachable
• inspect journal events for fallback/failure clues

Missing progress details

Check:

• journal is attached to language
• timeline events are being emitted
• persistence target (Mongo) is available

Artifact URL issues

Check:

• MinIO endpoint/access credentials
• bucket existence and object key prefix
• signed URL generation path in MinioArchive

Conversation tests not discovered by lingo test

Check:

• test functions use @lang.conversation
• target path/module resolves correctly
• function remains a callable after decorators