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

# Troubleshooting

Common errors and how to fix them

Having issues with RagnaSync? This page covers common errors you might see in your server console and how to resolve them.

***

## Connection Errors

{% hint style="info" %}
Every connection error below is followed by a second console line pointing you back to this page (or to contact support) -- so if your console shows an error not listed here, it is worth checking again after an update.
{% endhint %}

### "Discord Guild ID is required."

**What it means:** Your Discord server ID is missing or empty.

**How to fix:**

1. Get your Discord server ID (right-click server icon → Copy Server ID)
2. Open `conf/channels.conf`
3. Set your Discord server ID:

```
ragnasync_discord_id: "1234567890123456789"
```

***

### "Invalid ragnasync\_discord\_id value found inside channels.conf"

**What it means:** The Discord server ID you entered is not a valid format.

**How to fix:**

* Discord server IDs are 17-19 digit numbers
* Make sure it's wrapped in quotes: `"1234567890123456789"`
* Don't leave the default placeholder value

***

### "Set ragnasync\_discord\_guid in channels.conf"

**What it means:** Your Discord GUID (security key) is missing, so your server can't prove who it is.

**How to fix:**

1. Contact RagnaSync support to get your Discord GUID
2. Add it to your `channels.conf`:

```
ragnasync_discord_guid: "your-guid-here"
```

{% hint style="info" %}
The Discord GUID is provided by RagnaSync during installation. If you don't have it, contact support.
{% endhint %}

***

### "guid does not match discord\_id. Reissue both."

**What it means:** Your `ragnasync_discord_guid` isn't the one that belongs to your `ragnasync_discord_id`. The two are issued together as a pair, and your server won't connect unless they match.

**How to fix:**

* Double-check you copied the GUID correctly (no extra spaces)
* **Moved to a new Discord server?** This is the usual cause. Changing `ragnasync_discord_id` without a matching new GUID lands here — ask support to reissue **both** values together
* **Copied `channels.conf` from another server?** The GUID in it belongs to that server's Discord, not yours. Ask support for your own pair
* Contact RagnaSync support if the problem persists

{% hint style="warning" %}
Your Discord GUID is also your dashboard login. Treat it like a password — don't paste it into a config you share with anyone else.
{% endhint %}

***

### "IP blocked: invalid guid" / "IP blocked: missing guid"

**What it means:** Your server has been temporarily blocked after several connection attempts with a wrong or missing GUID.

**How to fix:**

* Wait for the block to expire (the error message shows remaining time)
* While waiting, verify your `channels.conf` settings are correct
* Once the block expires, your server will retry automatically

{% hint style="info" %}
The block is scoped to your Discord server, not to your whole machine — an unrelated Discord server sharing the same IP (shared hosting, a multi-tenant VPS) keeps connecting normally. Your own Ragnarok servers are blocked alongside it if they use the same `ragnasync_discord_id`, because they share the one GUID that needs fixing.
{% endhint %}

***

### "GUID already connected. Use unique GUID."

**What you'll see in console:**

```
[Info]: RagnaSync Service: Connection accepted
[Status]: RagnaSync Service: Logging in to server...
[Error]: [RagnaSync] GUID already connected. Use unique GUID.
[Status]: RagnaSync service has disconnected.
[Status]: RagnaSync service: Will attempt reconnection in 5 minute(s)
```

**What it means:** Another server is already connected using the same `client_guid` in your `channels.conf`. This commonly happens when you have both a test server and live server using the same GUID.

**How to fix:**

1. **Quick Fix: Disconnect your test server** - Simply disconnect your test server until your live server connection is established. This is the easiest solution if you don't need both servers connected simultaneously.
2. **For simultaneous connections: Use unique GUIDs** - If you need both test and live servers connected at the same time, each server **must have a different `client_guid`** in their `channels.conf` file.

{% hint style="info" %}
**Running multiple servers long-term?** Don't hand-edit `channels.conf` on each one -- put the per-server `ragnasync_client_guid` in `conf/import/channels.txt` instead, which is gitignored by default so each environment keeps its own identity without fighting over a shared, git-tracked file. See [Using conf/import/channels.txt](https://docs.ragnasync.com/getting-started/pages/wH2yl4PsWTEIyYft1ZzU#using-conf-import-channels.txt) for the full setup.
{% endhint %}

After making changes, use `@reloadsync` in-game to restart the RagnaSync service.

{% hint style="info" %}
If you recently restarted your server, wait a few minutes for the old connection to timeout before trying again.
{% endhint %}

***

### "Client outdated. Contact support to upgrade."

**What it means:** Your RagnaSync client files are too old for the current protocol -- a bigger gap than a normal version bump.

**How to fix:**

* Contact RagnaSync support for updated installation files
* Make sure you're using the files provided by our installation team, not a copy from another server

***

### "Upgrade required. \[version] (Latest: \[version]). N attempts left"

**What it means:** Your client version is below the minimum supported version. Repeated attempts on an outdated version temporarily block your IP (see "IP blocked" below).

**How to fix:**

* Update to the latest RagnaSync client files
* Check the version shown in the message against the "Latest" version -- if you're already on it, contact support, as this usually means an update did not fully apply

***

### "IP blocked. Nm remaining"

**What it means:** Your server kept connecting with an outdated client version, so your IP is temporarily blocked from retrying.

**How to fix:**

* Wait for the block to expire (the error message shows remaining minutes)
* Update your client files while you wait, so the next attempt succeeds
* Once the block expires, `@reloadsync` or the automatic reconnect will try again

***

### "Invalid client GUID format. Contact Support."

**What it means:** The `ragnasync_client_guid` in your `channels.conf` isn't a valid GUID -- it may be corrupted, truncated, or edited by hand.

**How to fix:**

* Contact RagnaSync support for your correct `ragnasync_client_guid`
* Don't hand-edit this value -- copy it exactly as issued

***

### "Maximum reconnection attempts reached. Stopping."

**What it means:** Your server tried to connect multiple times but failed each time.

**How to fix:**

1. Check your `channels.conf` settings are correct
2. Verify your Discord server ID and GUIDs
3. Use `@reloadsync` to try connecting again
4. If issues persist, contact support

***

## Script Errors

### "Script validation failed: Missing required fields"

**What it means:** A RagnaScript message is missing required data.

**How to fix:** Make sure your RagnaScript calls include all required fields:

```c
// Required fields for most scripts:
ragnascript("[action: message][channel: 1234567890][name: " + strcharinfo(0) + "][message: Hello][account_id: " + getcharid(3) + "][char_id: " + getcharid(0) + "]");
```

Common missing fields:

* `action` - The script type
* `channel` - Discord channel ID
* `account_id` - Player's account ID
* `char_id` - Player's character ID

***

### "Message is too long (max 2000 characters)"

**What it means:** The message you're trying to send exceeds Discord's limit.

**How to fix:**

* Shorten your message to under 2000 characters
* For NPC scripts, add length validation:

```c
if (getstrlen(.@message$) > 1900) {
    mes "Message too long!";
    close;
}
```

***

### "Discord server is not connected, message not queued"

**What it means:** Your server isn't connected to RagnaSync, so messages can't be sent.

**How to fix:**

1. Check connection status with `@syncstatus`
2. If disconnected, use `@reloadsync` to reconnect
3. Verify your `channels.conf` settings

***

### "Queue full, dropping message"

**What it means:** Too many messages are waiting to be sent. New messages are being dropped.

**How to fix:**

* This usually means your server is sending messages faster than they can be delivered
* Add rate limiting to your NPC scripts
* Check if your connection is stable

***

## Channel Errors

### "Invalid channel ID" / "Default channel ID detected"

**What it means:** The Discord channel ID is missing or still set to the placeholder value.

**How to fix:**

1. Get your Discord channel ID (right-click channel → Copy Channel ID)
2. Update your channel configuration:

```
{
    name: "#global"
    alias: "[Global]"
    discord_channel_id: "1234567890123456789"  // Your actual channel ID
}
```

{% hint style="warning" %}
Don't forget to uncomment the line by removing `//` if it's commented out.
{% endhint %}

***

## GM Command Reference

Use these commands to manage RagnaSync:

| Command       | Description                                        |
| ------------- | -------------------------------------------------- |
| `@startsync`  | Start RagnaSync service                            |
| `@stopsync`   | Stop RagnaSync service                             |
| `@reloadsync` | Reload config and reconnect (alias: `@syncreload`) |
| `@syncstatus` | Check connection status                            |

***

## Still Having Issues?

If you've tried the solutions above and still have problems:

1. **Check your server console** for the exact error message
2. **Verify all settings** in `channels.conf` match what RagnaSync provided
3. **Contact support** with:
   * The exact error message
   * Your Discord server ID
   * When the problem started

[Contact RagnaSync Support](https://discord.gg/FQjjeaMZK2)