Troubleshooting

Start with these four checks#

Most problems show up in the first minute of a server start.

Run astroshield status in the server console. It shows whether the dashboard is Online, the license status and whether the configuration is loaded. See Console commands.
Read the banner. Its Status line says License active or tells you the problem. See License statuses.
Check server.cfg. The three AstroShield lines must be there. See Installation.
Check .key. resources/AstroShield/.key must exist. It is a hidden file.

Connection and license messages#

These are printed by AstroShield in the server console.

Message	What it means	What to do
`No license key found (.key file)`	The `.key` file is missing, empty or in the wrong folder.	Make sure `resources/AstroShield/.key` exists. Upload hidden files, or download the resource again.
`Missing permissions! Add to server.cfg:`	The two permission lines are missing. AstroShield does not connect without them.	Add `add_ace resource.AstroShield command allow` and `add_unsafe_child_process_permission AstroShield`, then restart.
`Auth failed: Invalid Token`	The `.key` file was edited or damaged.	Download the resource again and replace the file.
`Auth failed: IP Locked`	The server connected from another IP than the one the license is locked to.	Request an IP reset.
`Auth failed: Already Connected`	A server with the same key is already connected.	Stop the other one. After a crash, wait a minute and run `restart AstroShield`.
`Auth failed: License Expired`	The license ran out.	Renew it, then `restart AstroShield`.
`Auth failed: License Banned`	The license was suspended.	Contact support.
`Auth failed: Server config not found`	The license has no server configuration. Banner: `This license is inactive`.	Contact support.
`Auth failed: IP Bind Failed` or `Database error`	The backend could not save the IP. Usually temporary.	Run `restart AstroShield` a little later. If it stays, contact support.
`Disconnected from bridge (code: ...)` then `Reconnecting in Ns...`	The connection to the backend dropped. AstroShield reconnects by itself, waiting 5 seconds more each time, up to 30.	Usually nothing. If it keeps happening, check your network and firewall.
`WebSocket error`	The backend could not be reached.	Allow outbound TCP from the server to `server.matyxx0.dev` on port `53785`, and check DNS.

A refused license does not retry

After Auth failed: ... the resource stops trying. Once you have fixed the cause, run restart AstroShield. Reconnecting after a normal network drop is automatic.

Other console messages#

Message	What it means	What to do
`Automatic astroinstall skipped: missing permissions`	The permission lines are missing, so AstroShield cannot edit manifests.	Add the lines from the first table and restart.
`Failed: <resource>` during `astroinstall`	That resource's manifest could not be read or written.	Fix the file permission, or add `shared_script '@AstroShield/shared-obfuscated.lua'` to its manifest by hand.
`Update failed: ...`	The automatic update could not finish.	See Updating.
`Update vX is available. Auto update is off in the dashboard`	A newer version exists and you switched auto-update off.	Switch it on, or update by hand.
`RegisterConsoleListener is not available on this server build`	Your server build is too old for the live console.	Update your FiveM server build.
`Custom rules could not be handed to the game script`	The resource files are from different versions.	Update the resource. See Updating.
`Config: waiting for dashboard` in `astroshield status`	The configuration has not arrived yet.	Wait a few seconds. If it stays, the connection or license has a problem, see above.

The dashboard shows my server as offline#

AstroShield is not connected to the backend. Work through the first table: .key, permission lines, the Auth failed message, your firewall. astroshield status tells you which one it is.

The server connects, but nothing is detected#

Check that Dev Mode is off. In Dev Mode nothing is punished. See Configuration.
Check that the detections you expect are switched on, some are off by default. See the detection reference.
Make sure you restarted a second time after the first start, so your resources load the guard. See Installation.
Check that the player is not an exempt admin. See Permissions and whitelisting.

A player was flagged by mistake#

Unban them: dashboard, Bans, Remove. See Bans.
Open the ban record. The Detection and Reason tell you what fired, and the evidence clip shows what the player did.
Turn on Dev Mode and reproduce it. The console prints the detection with its data.
Fix the cause:
- A script of yours does something on purpose: announce it with an allowance, or install the shared guard so it is recognized.
- A trusted script triggers many events: ignore the event.
- A detection is too sensitive for your server: switch it off or change its options in Configuration.

A resource misbehaves after installing AstroShield#

Run astrouninstall, restart that resource and see whether the problem goes away. If it does, add the resource to Ignored Resources and report it on Discord with the resource name and a link to it. See Shared guard.

The in-game panel does not open#

See the table at the end of In-game panel. The usual cause is a missing permission or a Discord client that was not running when the player joined.

Performance#

AstroShield is built to run in the background. If you suspect it, open resmon in the client and check the time of AstroShield and of the resource you suspect. Turn Dev Mode on briefly: if the cost goes away, a detection is working very hard on your server, and the console shows which. Send what you find to support.

What to send when you ask for help#

Send support these, never your .key:

the output of astroshield status,
the lines of the console around the problem,
the version in resources/AstroShield/.version,
your server build and framework.

Command Palette