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

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.

"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"

The Discord GUID is provided by RagnaSync during installation. If you don't have it, contact support.

---

"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

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.

---

"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

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.

---

"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.

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 for the full setup.

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

If you recently restarted your server, wait a few minutes for the old connection to timeout before trying again.

---

"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:

// 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:

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
}

Don't forget to uncomment the line by removing // if it's commented out.

---

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