> For the complete documentation index, see [llms.txt](https://wiki.auraplugins.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.auraplugins.eu/help/troubleshooting.md).

# Troubleshooting

## First reflex, always

```
/aurasounds debug <sound>
```

Stand where the sound *should* play. Every condition shows a live ✔ or ✘ for you. In most "it doesn't play" cases, one ✘ tells you exactly why (wrong biome key, you're above `max-y`, it's daytime…).

## "My sound never plays"

1. `/aurasounds list` — does the sound appear? If not, its YAML failed to load: check the console; AuraSounds logs *which file* and *which field* is invalid, then `/aurasounds reload`.
2. `/aurasounds info <sound>` — is it `enabled`? Are the source points in the right world and coordinates?
3. `/aurasounds play <sound>` — force it. If you hear it now, playback is fine and the issue is **conditions** or **distance** → `debug`.
4. Ambient: are you within `radius` of a source point?
5. `/aurasounds on` — make sure you didn't disable ambience for yourself long ago.

## "Custom sound is silent, vanilla works"

The classic resource-pack chain. Check in order:

1. **Is the pack applied client-side?** ItemsAdder/Nexo: did the pack prompt appear and did you accept? Manual pack: is the server `resource-pack` URL set and reachable?
2. **Does the key match?** `mypack:swamp` in the sound file must exist exactly in the pack's `sounds.json`. Test directly:

   ```
   /playsound mypack:swamp ambient @s
   ```

   If `/playsound` is silent too, the problem is in the pack, not in AuraSounds.
3. **ItemsAdder/Nexo not finished loading?** AuraSounds waits for their load event automatically — sounds activate a few seconds after startup. If the hooked plugin is missing entirely, the console shows one clear warning and that sound is disabled.
4. **OGG format** — Minecraft only plays OGG Vorbis. For positional sounds, files should be **mono** (stereo plays at constant volume everywhere).

## "Music doesn't change between my regions"

* One music per player: check the `priority` values of overlapping zones — the highest wins.
* Confirm the WorldGuard region name in the sound matches exactly (`/rg info <region>`).
* Walk across the border and give it up to one check interval (default 1 s).

## "Loops have a gap / overlap themselves"

`loop.duration` must equal the real audio length. Too short → the sound overlaps itself; too long → silent gap. Measure your file precisely (ffprobe or your editor) and set `interval` for any *intentional* silence between repetitions.

## "It broke after a Minecraft update"

AuraSounds uses only stable APIs (no NMS), so minor updates rarely require anything. If a sound uses vanilla keys that Mojang renamed, fix the key in the YAML. Check the plugin page for a version note before reporting.

## Reporting a bug

Please include: plugin version, server software + version (`/version`), the sound's YAML file, and the console output with `debug: true` enabled in `config.yml`. That combination lets us reproduce nearly everything.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.auraplugins.eu/help/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.