> For the complete documentation index, see [llms.txt](https://docs.spoof.dev/asteroid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spoof.dev/asteroid/faq-and-troubleshooting.md).

# FAQ and Troubleshooting

Common questions and fixes. If your issue is not here, join the Discord and open a ticket: [discord.gg/dn8YE2Ctbv](https://discord.gg/dn8YE2Ctbv)

## No fake players are spawning

Check these in order:

1. Did you generate profiles? Run `/asteroid profiles generate 100`. Without profiles, there is nobody to spawn.
2. Is spoofing on? Run `/asteroid toggle` and confirm it is enabled.
3. Are your limits sensible? If `max` is 0, or `min` is 0 with no real players and a low multiplier, few or no fakes will appear. Try `min: 2` while testing.
4. Reload after config edits with `/asteroid reload`.

## The commands do not work or I cannot see them

Only allowed UUIDs can use Asteroid commands, and others do not even see them. Add yourself with the instant-setup command shown in the config, or add your UUID under `access.allowed_uuids`.

## Fake players get kicked the moment they join

This is usually a login or auth plugin rejecting them during the login handshake. Two options:

* Enable the Login addon so fakes log in automatically.
* As a simpler fix, set `players.skipLoginAllow: true` to force the login to be accepted.

## Fake players get kicked for keepalive timeout

Asteroid suppresses keepalive on standard Paper and Spigot. If you see repeated "kicked due to keepalive timeout" messages, you are likely on a modified server fork that runs its own keepalive check. Report your exact server software on the Discord so it can be handled for that fork.

## Errors mentioning CraftPlayer on 1.20.6 or newer

Some Paper forks do not fully remap Minecraft's internal classes. On 1.20.6 and up, set `spoof.paper1206PlusFix: true`, then restart.

## Another plugin throws errors when a fake player joins

Some plugins try to attach to a real network connection on join. Fake players use a lightweight stub connection, so a plugin that does not check for this can log an error. In most cases the fake still spawns fine and the error is harmless noise from the other plugin.

## Redis or proxy will not connect

* Make sure Asteroid and AsteroidLibs are installed on the proxy too, not just the backend servers.
* Check that `server_name` matches your proxy config exactly.
* Check your Redis URI. If your password contains special characters like `@`, remember Asteroid reads everything up to the last `@` as the password.

## The same fake name shows up on two servers

You are sharing a database across servers. Turn on `database.prevent-duplicate-connections: true`. This only works with `mysql` or `mongodb`, since `sqlite` is local to each server.

## The server is lagging with many fake players

1. Turn off features you do not use: `allowSchedulerFeature` and `allowEntityPickup`.
2. Reduce or disable movement abilities.
3. As a last resort, enable `performanceMode` for the lightest possible fakes.

## AI is not replying

1. Set `ai.enabled: true`.
2. Make sure `ai.apiKey` is a valid OpenRouter key.
3. Check that `playerToAI.enabled` is true and `response_chance` is not too low to notice.
4. Confirm the model in `ai_model` is a valid OpenRouter model.

## How many profiles should I generate

Aim for several times your maximum fake player count, so there is always variety. If your `max` is 30, a few hundred profiles is comfortable.

## How do I hide that I use Asteroid

* Disguise the plugin name in the `spoof.plugin` section so it shows as something else in `/plugins`.
* Keep `showFakePlayerOnJoin: false` if you do not want join lines in console.
* Consider `showAnonPlayers: true` so hovering the player count does not reveal fake names.