I'll try to cover almost every question answered on #craftirc here.

For anything else (or if you have no idea what to do), join #craftirc, ask any questions or state your problem, and wait patiently for a good amount of time so someone can answer your question, thanks. Webchat link here.

(The Command list was moved here here)

Common errors

Click to see relevant answers:


Do I need my own IRC server / Is CraftIRC an IRC server / Does CraftIRC use real IRC users for each player?

No. CraftIRC is just an IRC client which is usually used with one single irc bot connected to an existing IRC server.

You don't need to own an irc server to use CraftIRC, you can just join a new channel in a public network like esper

If you want to use real IRC users for each player, and can admin an irc server, you should try a plugin like IRCTransport

Does CraftIRC work in the latest bukkit version?

99% of the time, yes. Bukkit developers usually announce if they change stuff that would break enough to make CraftIRC stop working. Install it and if you get errors, ask.

How do I check my CraftIRC version?

/version CraftIRC

What's IRC and how do I use it?

If you need to ask this question you probably don't need CraftIRC.

Can I use CraftIRC to manage the channel topic / moderate the channel / have additional irc bot commands etc?

No. A standalone irc bot is recommended for this stuff and is going to give greater flexibility. You might be able to hack some extra simple features with /ircraw, see the full command list below.

General usage

Autopaths or manual paths?

Use autopaths if you're lazy and only need a basic setup that uses a single irc channel that gets all messages from minecraft.

Anything more complex than that will need manual paths. Sometimes autopaths get stuff wrong, and the ways to get that fixed are harder than just doing manual paths.

If you're confused on what endpoints, tags and paths are, read this page.

How to enable .c / .cmd

  • Make sure you have OP status according to what the admin-prefixes config entry says
  • Set admin: true in default-attributes (or, if using manual paths, in the channel->console path)
  • Add the commands you want to use to the console-commands whitelist.
  • To allow all the commands, add "*" to the list of console-commands


First two steps of the previous question:

  • OP status in the channel
  • admin: true

How do I reload the config without restarting the server?

Do /ircreload. Don't use "plugin managers" such as "plugman". The bukkit /reload command might work, but can also break other plugins.

Can I send PMs with commands to the bot? / Send PMs to in-game players?

Not at the moment.

Can you bind CraftIRC to IPv6?

Yes. Just put the address in bind-address.

Color code for "foreground text" on irc? / IRC clients with black/white backgrounds can't read anything

Use the reset code (%o%) instead of black/white/foreground/background.

Sometimes the %prefix% or %suffix% variables set by plugins use a "black" color. if they always set "black" after the prefix/suffix and don't change the nick color to something else, or you don't care about the nick color being different, just write %o% after %prefix% and %suffix%

Language / international support / Encoding?

Since 3.9.5 you can configure the encoding in the bots section of the config. Previous versions rely on the java/operating system environment. UTF-8 is a sane default that is supported by most irc clients out of the box, except icechat. Don't use icechat.

What webchat should I use?

Is there a way to see private conversations of players, like "socialspy"?

Not at the moment. Someone could write a plugin for it if you really need it.

Path filters, Replacement filters

Path filters were broken before, but they are fixed since 3.9.5. They discard messages that match the specified criteria.

Replacement filters are at the end of the config file, with self-documenting comments.

Both of these use "regular expressions". If you don't what these are, they can look like normal text, but the following symbols have special meaning:

^ $ . + ? * { } [ ] ( )

You can put a backslash (\) before these and otherwise pretend that it's just plain text. If you want to know more about the meaning of this character, here's the most concise guide I've seen on the topic

Formatting .cmd replies

You can set formatting.from-game.generic to add something before or after the command reply.

Using CraftIRC for cross-server chat


Check the rules of your irc network regarding bots before doing this.

In particular, doing this in esper can get you banned from the network.

There might be better options to do this, but some people like to use CraftIRC for it. Here's a rough guide on stuff you can do to make it seamless:

  • Create a private/secret channel in a network.
  • Install craftirc bot in each server, make them join that channel.
  • Do a manual paths configuration if you want fine-tuning of the messages later.
  • Each bot can have a nick, this nick can be aliased to something that looks nicer and identifies the server better using irc-nickname-map
  • You can disable all messages except chat using default-attributes
  • You can set a formatting that is so minimal that all you see is "[Server] message", where Server was originally the nick. You can also use colors to make it look nice,
  • You can use path filters to remove some messages from the other bots - for example, don't show when someone joins to a different server to in-game players, but show everything on irc. Using these requires a minimal knowledge of regular expressions

Showing IRC OPs as "admins" or "moderators" in-game

You can use replacement filters to turn the irc prefix that usually says @ into something nicer. Here's an example, adapt it as you wish.

In the formatting section:

        chat: '%ircPrefix% <%sender%> %message%'

At the bottom of the config, in the replacement filters section:

        - '@': '%red%[Admin]%reset%'
        - '%': '%green%[Moderator]%reset%'
        - '\+': '%yellow%[Awesome dude]%reset%'

Note that the last one uses '\+' because these are regular expressions and + is a special character there. Putting a backslash before removes its meaning.

Issues and errors

First time configuration, no messages are relayed and there are no other chat plugins

You might have missed something in the config that disables everything. So read the whole config again, pay attention to the sections that say "CHANGES REQUIRED", and see if you got everything right.

If you did change the part that disables everything, and it's still broken, join irc and post a link to a pastebin of your current config.yml (remember to remove passwords from it)

java.net.ConnectException: Connection timed out

This kind of error means you have network issues, and in the case of craftirc, it means that it failed to connect to the IRC server.

If this is your first time configuring craftirc, your hosting provider might be blocking IRC connections. In this case:

  • You should check the Terms of Service of your provider to see if they explicitly forbid IRC usage - if they do, find a better host
  • You can send them a support ticket asking if it really is blocked intentionally, and if it is, if they can let you use it.
  • You can try setting a different port number to connect to the server.
    • The default port is 6667, some servers allow connections in any port between 6660 and 6669, some servers allow connections in completely different ports, such as 5555 for esper.net.
  • You can try using SSL to connect, usually the port number for this is 6697, change both ssl: true and port: 6697 in the config.

It can also be a general issue with the network, or it can be the remote IRC server being down.

A chat plugin is setting the %sender% field to something weird, I just want the username.

Use %realSender% instead.

Admin attribute not working on paths

It must be in the path from the irc channel to "console" for commands.

For /admins! should be from minecraft to irc channels (TODO verify).

You can always use the one in default-attributes to apply for all paths, and this is also the only way to do it with autopaths.

"Error: See CraftIRC console"

Have you considered checking the server console for errors?

"Could not find record settings.formatting.from-game.say"

Add line 88 from this link to the corresponding place of your config

You have to do this manually since CraftIRC never overwrites your config, not even after updating. Anyone who has been using the same config file for a long time is encouraged to check the differences with the latest version.

The color of a player changes if the username starts with a number

Should be fixed after updating to 3.9.5.

"Muted" chat displays on irc anyway

If you set cancelled-tag to something other than '' (that's an empty string, or two quotes with nothing in the middle), CraftIRC will handle these messages too. If you did it to support a chat plugin like factions, you're out of luck. If you don't know why it's set, change it back.

Developing plugins that use CraftIRC

Are there docs?

Almost. There's an example plugin here

How do I cancel a chat message to CraftIRC only?

You can only cancel the whole chat event at the moment, and send it to the chat yourself. A solution for this might appear in CraftIRC4.