# Troubleshooting

> Diagnose and resolve Ludus deployment, networking, template, WireGuard, Proxmox, and Ansible issues. Use when users report failures, errors, unreachable systems, failed joins, or unexpected behavior during build or deploy.

- **Type:** Skill
- **Install:** `agentstack add skill-badsectorlabs-ludus-skills-troubleshooting`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [badsectorlabs](https://agentstack.voostack.com/s/badsectorlabs)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [badsectorlabs](https://github.com/badsectorlabs)
- **Source:** https://github.com/badsectorlabs/ludus-skills/tree/main/skills/troubleshooting
- **Website:** https://docs.ludus.cloud/docs/using-ludus/mcp

## Install

```sh
agentstack add skill-badsectorlabs-ludus-skills-troubleshooting
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Ludus Troubleshooting

Use this skill to triage user-reported failures quickly, categorize errors, and provide targeted remediation steps.

## Diagnostic Workflow

1. Gather context and exact error output.
2. Check range deployment status and recent errors.
3. Review deployment logs for failure details.
4. Identify the failure category using the known error catalog.
5. Inspect the current range config for misconfigurations.
6. Provide targeted fixes with concrete steps.
7. Define clear verification steps to confirm recovery.

## Key Diagnostic Information

When triaging, gather these in order of usefulness:

- **Range status** — is the deployment running, failed, or complete?
- **Deployment errors** — the most recent error output from a deploy.
- **Deployment logs** — full log stream for tracing failure context.
- **Template status** — are required templates built and available?
- **Range config** — does the YAML match what the user intended?
- **Testing mode status** — is testing mode active, and are network rules in effect?

## Common Patterns

- Network issues often trace back to dnsmasq or NAT bridge state.
- Ansible failures often involve WinRM (Windows) or SSH reachability (Linux).
- Domain join failures usually involve DNS ordering or timing.
- Template failures are commonly ISO download or disk-space related.

## References

- Use `references/common-errors.md` for known errors, root causes, and fix procedures.
- Use `https://docs.ludus.cloud/docs/troubleshooting/client` for client and CLI troubleshooting details.
- Use `https://docs.ludus.cloud/docs/troubleshooting/network/` and `https://docs.ludus.cloud/docs/troubleshooting/wireguard/` for network and connectivity issues.
- For uninstalling Ludus, direct users to the official guide at `https://docs.ludus.cloud/docs/troubleshooting/uninstall` rather than performing the steps yourself.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [badsectorlabs](https://github.com/badsectorlabs)
- **Source:** [badsectorlabs/ludus-skills](https://github.com/badsectorlabs/ludus-skills)
- **License:** MIT
- **Homepage:** https://docs.ludus.cloud/docs/using-ludus/mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-badsectorlabs-ludus-skills-troubleshooting
- Seller: https://agentstack.voostack.com/s/badsectorlabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.