Troubleshooting

Work through the matching section, then use diagnostics and support escalation if the issue remains.

Missing agents

Check	Action
Agent not listed	Confirm it is a supported agent; Visu only lists registered adapters
Agent listed but off	Enable it in Settings → Agents and Save Changes
Capabilities look empty	Open the compatibility matrix; some agents only support MCP or a single feature
Still unusable after enable	Verify the agent itself is installed and can run outside Visu

Missing Workspaces or projects

• Register the folder under Workspaces → Manage Workspaces (or during setup).
• Visu does not auto-register every Git repo on disk.
• If a path moved, edit or re-add the Workspace registration.

Missing Library items

• Confirm the correct Library is active (Settings → Libraries).
• Filter/search in Library; clear type filters.
• Instruction documents appear only when Advanced / Labs → Agent Instruction Documents is enabled.
• Imported items appear after a completed review/apply: check Activity for the session outcome.

Unsupported features or scopes

Symptoms: agent excluded from assignment, warning copy, or no file written.

1. Compare the feature and destination with the Supported agents matrix.
2. Try the other scope (Global vs Workspace) if only one is supported.
3. For gated features, read the warning: content may need agent-specific shape.
4. Do not force unsupported combinations by hand-editing both sides; you will create conflicts Visu cannot reconcile cleanly.

Invalid configuration

• Save errors stay beside the Library draft: fix required fields and validation messages.
• MCP local servers need a runnable command on each OS you target.
• Skill packages need valid SKILL.md structure.
• Trigger commands should be safe and explicit; disable unknown triggers.

Failed synchronization

1. Open Activity for the session summary and linked results.
2. Re-run sync and complete every required review decision (conflicts cannot be skipped).
3. Confirm live updates vs deferred writes (Settings → Advanced / Labs).
4. Check Settings → Diagnostics for the durable log path and inspect recent entries.
5. Verify filesystem permissions on the Library folder and agent config paths.
6. If only one agent fails, test whether that agent can read/write its config outside Visu.

Conflict guidance

• Prefer Library when the Library is the source of truth you maintain.
• Prefer Import when the agent has newer intentional external edits you want to capture.
• Avoid applying bulk deletes until you understand whether the agent-only file is unmanaged content you still need.

Logs and diagnostics

• Activity: current session only
• Settings → Diagnostics: durable synchronization diagnostic log path
• Application version: Settings → Updates

Capture version, OS, agent name, feature, scope, and the failing action before escalating.

Safe recovery

1. Pause live updates if writes are thrashing.
2. Back up the Library folder and critical agent config files.
3. Disable problematic agents temporarily.
4. Re-enable agents one at a time and sync with review.
5. Re-enter sensitive MCP values if secrets are missing after a migration.
6. As a last resort, remove a bad assignment rather than deleting the Library item.

Support escalation

Contact Angry Software Solutions through the contact page with:

• VisuAgent Manager version
• Operating system
• Agents and scopes involved
• Whether the Library is new, imported, or shared
• Steps to reproduce
• Relevant Activity messages and non-secret diagnostic excerpts

Do not send plaintext secrets, license keys you must rotate, or entire home directories.

Related pages

• First-run setup
• Configuration item lifecycle
• Data and security
• Product page